[SqlStatement] Fix prefetch CI failures: cross-type string read, clang-tidy, docs, style

Address the CI matrix failures from the block-prefetch commit:

- Cross-type read regression (the PostgreSQL/Windows dbtool failures): reading a
  prefetched numeric/temporal/GUID column as a string (GetColumn<std::string>,
  as dbtool's generic `exec` printer does) returned an empty string because
  ConvertCell only rendered character-bound cells. RenderCellAsUtf8 now formats
  every bound type to text (integers byte-identical to the driver; floating/
  temporal/GUID via std::formatter), matching the per-row SQLGetData(SQL_C_CHAR)
  behaviour. Adds a [prefetch] regression test for the all-numeric-read-as-text
  case.
- clang-tidy (-warnings-as-errors): split is moot — fixed at source. Test file:
  math-missing-parentheses, integer-sign-comparison, nested conditional operator,
  std::move on trivially-copyable fixed strings, unchecked optional access.
  Header: unused-lambda-capture (explicit this-> on the member call). ConvertCell
  was also split into per-category helpers to stay under the cognitive-complexity
  threshold.
- Doc coverage (doxygen): @ref PrefetchDepthDefault -> @c (it is a value, not a
  ref target) in SqlConnection.hpp and SqlConnectInfo.hpp; drop the @param naming
  an unnamed parameter on SqlLogger::OnFetchBlock (described in the brief instead).
- C++ style (clang-format-22): restore the single-line empty deleter lambda.

Verified: clangcl-debug builds clean; [prefetch] suite green on sqlite3,
mssql2022 (Docker), postgres (Docker); dbtool `exec` renders numeric columns.

Signed-off-by: Christian Parpart <c.parpart@lastrada.net>

Author: Christian Parpart

src/Lightweight/SqlConnectInfo.hpp

@@ -76,7 +76,7 @@ struct [[nodiscard]] SqlConnectionDataSource
     /// (rows requested per @c SQLFetchScroll round-trip on the transparent per-row fetch path).
     ///
     /// A value <= 1 disables prefetch (every classic loop keeps issuing one @c SQLFetch per row).
-    /// Defaults to @ref PrefetchDepthDefault. Has effect only on backends whose driver supports
+    /// Defaults to @c PrefetchDepthDefault. Has effect only on backends whose driver supports
     /// native row-array fetching (see @c SqlConnection::SupportsNativeRowArrayFetch).
     std::size_t defaultPrefetchDepth = PrefetchDepthDefault;
 

src/Lightweight/SqlConnection.hpp

@@ -191,7 +191,7 @@ class SqlConnection final
     /// instead of issuing one @c SQLFetch per row. A value <= 1 disables prefetch. Effective only when
     /// @ref SupportsNativeRowArrayFetch is true; otherwise statements fall back to per-row fetching.
     ///
-    /// @return The configured default prefetch depth (defaults to @ref PrefetchDepthDefault).
+    /// @return The configured default prefetch depth (defaults to @c PrefetchDepthDefault).
     [[nodiscard]] LIGHTWEIGHT_API std::size_t DefaultPrefetchDepth() const noexcept;
 
     /// @brief Sets the default block-prefetch depth for statements created on this connection.

src/Lightweight/SqlLogger.hpp

@@ -118,8 +118,7 @@ class SqlLogger
     ///
     /// Non-pure with an empty default so existing loggers need no change; override to observe how many
     /// network round-trips a query actually cost (N rows at depth D collapse to @c ceil(N/D) blocks).
-    ///
-    /// @param rowsInBlock Number of rows materialized by this block fetch (0 at end of result set).
+    /// The argument is the number of rows materialized by this block fetch (0 at end of result set).
     virtual void OnFetchBlock(std::size_t /*rowsInBlock*/) {}
 
     /// Invoked when fetching is done.

src/Lightweight/SqlStatement.cpp

@@ -268,8 +268,7 @@ SqlStatement::SqlStatement(SqlConnection& relatedConnection):
 }
 
 SqlStatement::SqlStatement(std::nullopt_t /*nullopt*/):
-    m_data { const_cast<Data*>(&Data::NoData), [](Data* /*data*/) {
-            } }
+    m_data { const_cast<Data*>(&Data::NoData), [](Data* /*data*/) {} }
 {
 }
 

src/Lightweight/SqlStatement.hpp

@@ -1068,7 +1068,7 @@ void SqlStatement::BindOutputColumnsToRecord(Records*... records)
         ((EnumerateRecordMembers(*records,
                                  [this, &i]<size_t I, typename FieldType>(FieldType& value) {
                                      ++i;
-                                     RecordPrefetchOutputColumn<FieldType>(i, &value);
+                                     this->RecordPrefetchOutputColumn<FieldType>(i, &value);
                                  })),
          ...);
         return;
@@ -1798,20 +1798,42 @@ namespace detail
         }
     }
 
+    /// @brief Renders a block-buffer cell to UTF-8 text. Character columns are returned verbatim;
+    /// numeric, temporal and GUID columns are formatted to their text form. This mirrors the driver's
+    /// @c SQL_C_CHAR conversion on the single-row @c GetColumn path so that reading a non-character column
+    /// as a string (e.g. a generic "print every column as text" loop) yields the value rather than an
+    /// empty string. Integer text is identical to the driver's; floating/temporal text uses the value
+    /// type's @c std::formatter, which is backend-independent.
+    [[nodiscard]] inline std::string RenderCellAsUtf8(RowArrayCursor const& cursor, std::size_t row, SQLUSMALLINT column)
+    {
+        switch (cursor.ColumnBoundType(column))
+        {
+            case RowArrayCursor::BoundType::Char:
+            case RowArrayCursor::BoundType::WChar:
+                return cursor.GetString(row, column).value_or(std::string {});
+            case RowArrayCursor::BoundType::Int64:
+                return std::format("{}", cursor.GetI64(row, column).value_or(0));
+            case RowArrayCursor::BoundType::Double:
+                return std::format("{}", cursor.GetF64(row, column).value_or(0.0));
+            case RowArrayCursor::BoundType::Date:
+                return std::format("{}", cursor.GetDate(row, column).value_or(SqlDate {}));
+            case RowArrayCursor::BoundType::Timestamp:
+                return std::format("{}", cursor.GetTimestamp(row, column).value_or(SqlDateTime {}));
+            case RowArrayCursor::BoundType::Guid:
+                return std::format("{}", cursor.GetGuid(row, column).value_or(SqlGuid {}));
+        }
+        return std::string {};
+    }
+
     /// @brief Reconstructs a string-like cell (plain @c std::string flavours and the Lightweight string
-    /// wrappers) from the block buffer. Character columns bind as @c Char (SQL_C_CHAR) or @c WChar
-    /// (SQL_C_WCHAR); a non-text bound type (only reachable via a cross-type read of a numeric/temporal
-    /// column) yields an empty value. Fixed-capacity strings get the same trailing trim the single-row
-    /// @c GetColumn path applies via @c SqlFixedString::PostProcessOutputColumn, so the value is
-    /// byte-identical; the UTF-8 bytes are then re-encoded to the target's element type.
+    /// wrappers) from the block buffer, rendering any bound type to text via @ref RenderCellAsUtf8.
+    /// Fixed-capacity strings get the same trailing trim the single-row @c GetColumn path applies via
+    /// @c SqlFixedString::PostProcessOutputColumn; the UTF-8 bytes are then re-encoded to the target's
+    /// element type.
     template <typename T>
     [[nodiscard]] inline T ReadStringLikeCell(RowArrayCursor const& cursor, std::size_t row, SQLUSMALLINT column)
     {
-        using BoundType = RowArrayCursor::BoundType;
-        auto const boundType = cursor.ColumnBoundType(column);
-        if (boundType != BoundType::Char && boundType != BoundType::WChar)
-            return T {};
-        auto utf8 = cursor.GetString(row, column).value_or(std::string {});
+        auto utf8 = RenderCellAsUtf8(cursor, row, column);
         if constexpr (SqlFixedStringCell<T>)
             TrimFixedStringBytes<T::PostRetrieveOperation>(utf8);
         return T { DecodeUtf8To<typename T::value_type>(utf8) };

src/tests/SqlStatementPrefetchTests.cpp

@@ -126,7 +126,7 @@ SqlStatement MakePerRowStatement()
 
 TEST_CASE_METHOD(SqlTestFixture, "Prefetch: raw GetColumn loop collapses round-trips", "[prefetch]")
 {
-    constexpr std::size_t rowCount = 2 * TestPrefetchDepth + 7; // crosses two block boundaries
+    constexpr std::size_t rowCount = (2 * TestPrefetchDepth) + 7; // crosses two block boundaries
 
     auto stmt = SqlStatement {};
     stmt.Connection().SetDefaultPrefetchDepth(TestPrefetchDepth);
@@ -154,6 +154,37 @@ TEST_CASE_METHOD(SqlTestFixture, "Prefetch: raw GetColumn loop collapses round-t
     CHECK(probe.blockFetches < rowCount); // proves batching: far fewer round-trips than rows
 }
 
+TEST_CASE_METHOD(SqlTestFixture, "Prefetch: numeric columns read as text render their value (cross-type)", "[prefetch]")
+{
+    // A generic "print every column as a string" loop (e.g. dbtool's `exec`) reads numeric columns via
+    // GetColumn<std::string>. On the per-row path the driver converts the value to text; the prefetch
+    // path must do the same rather than yield an empty string. Integer text is exact; the double is only
+    // checked for non-emptiness because its textual form is not portably defined.
+    auto stmt = SqlStatement {};
+    stmt.Connection().SetDefaultPrefetchDepth(TestPrefetchDepth);
+    CreateNumericTable(stmt);
+    constexpr std::size_t rowCount = TestPrefetchDepth + 5;
+    FillNumericTable(stmt, rowCount);
+
+    PrefetchProbe probe;
+    std::size_t seen = 0;
+    {
+        LoggerSwap const swap { probe };
+        auto cursor = stmt.ExecuteDirect(std::string { kNumericSelect });
+        while (cursor.FetchRow())
+        {
+            auto const rowNumber = static_cast<std::int64_t>(seen) + 1;
+            CHECK(cursor.GetColumn<std::string>(1) == std::format("{}", rowNumber));        // Id (exact)
+            CHECK(cursor.GetColumn<std::string>(2) == std::format("{}", rowNumber * 1000)); // Big (exact)
+            CHECK_FALSE(cursor.GetColumn<std::string>(3).empty());                          // Ratio (double)
+            CHECK(cursor.GetColumn<std::string>(4) == std::format("{}", rowNumber % 97));   // Mid (exact)
+            ++seen;
+        }
+    }
+    REQUIRE(seen == rowCount);
+    CHECK(probe.blockFetches >= 1); // the all-numeric result set is prefetched
+}
+
 TEST_CASE_METHOD(SqlTestFixture, "Prefetch: bound output columns with NULLs and optionals", "[prefetch]")
 {
     auto stmt = SqlStatement {};
@@ -193,8 +224,8 @@ TEST_CASE_METHOD(SqlTestFixture, "Prefetch: bound output columns with NULLs and
     CHECK(probe.blockFetches >= 2); // crossed at least one block boundary
     for (auto const i: std::views::iota(std::size_t { 0 }, rowCount))
     {
-        auto const rowNumber = i + 1;
-        CHECK(actual[i].first == static_cast<std::int64_t>(rowNumber));
+        auto const rowNumber = static_cast<std::int64_t>(i) + 1;
+        CHECK(actual[i].first == rowNumber);
         if (rowNumber % 5 == 0)
             CHECK_FALSE(actual[i].second.has_value());
         else
@@ -411,7 +442,13 @@ TEST_CASE_METHOD(SqlTestFixture, "Prefetch: string, fixed-string, wide and nulla
                      .Set("Note", SqlWildcard));
     for (auto const i: std::views::iota(std::size_t { 1 }, rowCount + 1))
     {
-        auto const name = i % 3 == 0 ? std::format("Grüße-{}", i) : (i % 3 == 1 ? std::string {} : std::format("row-{}", i));
+        auto const name = [i] {
+            if (i % 3 == 0)
+                return std::format("Grüße-{}", i);
+            if (i % 3 == 1)
+                return std::string {};
+            return std::format("row-{}", i);
+        }();
         auto const note = i % 7 == 0 ? std::optional<std::string> {} : std::optional<std::string> { std::format("n{}", i) };
         (void) stmt.Execute(static_cast<std::int64_t>(i),
                             name,
@@ -437,7 +474,9 @@ TEST_CASE_METHOD(SqlTestFixture, "Prefetch: string, fixed-string, wide and nulla
             auto wide = cursor.GetColumn<std::u16string>(3);
             auto tag = cursor.GetColumn<SqlTrimmedFixedString<8>>(4);
             auto note = cursor.GetNullableColumn<std::string>(5);
-            rows.emplace_back(id, std::move(name), std::move(wide), std::move(tag), std::move(note));
+            // name (SqlAnsiString<32>) and tag (SqlTrimmedFixedString<8>) are trivially copyable, so they
+            // are passed by value; only the heap-backed wide string and optional are moved.
+            rows.emplace_back(id, name, std::move(wide), tag, std::move(note));
         }
         return rows;
     };
@@ -473,8 +512,9 @@ TEST_CASE_METHOD(SqlTestFixture, "Prefetch: GUID column round-trips", "[prefetch
     stmt.Prepare(stmt.Query("PrefetchGuid").Insert().Set("Id", SqlWildcard).Set("Uid", SqlWildcard));
     for (auto const i: std::views::iota(std::size_t { 1 }, rowCount + 1))
     {
-        auto const uid = SqlGuid::TryParse(std::format("12345678-1234-1234-1234-{:012}", i)).value();
-        (void) stmt.Execute(static_cast<std::int64_t>(i), uid);
+        auto const parsedUid = SqlGuid::TryParse(std::format("12345678-1234-1234-1234-{:012}", i));
+        REQUIRE(parsedUid.has_value());
+        (void) stmt.Execute(static_cast<std::int64_t>(i), *parsedUid);
     }
 
     auto readGuids = [&](SqlStatement& source) {