From 92d5606e86f60d0b614060eee02223e9405177a0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?S=C3=A9bastien=20Rombauts?= Date: Sat, 24 Oct 2026 18:27:17 +0200 Subject: [PATCH 1/2] docs: clarify nullable text result usage Handle null text pointers in README output examples, correct the implicit conversion equivalence, and document borrowed result lifetimes for getColumns(). --- README.md | 7 +++++-- examples/example1/main.cpp | 2 +- include/SQLiteCpp/Statement.h | 6 +++++- 3 files changed, 11 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 91fd7c22..dc7956cb 100644 --- a/README.md +++ b/README.md @@ -387,7 +387,7 @@ try const char* value = query.getColumn(1); int size = query.getColumn(2); - std::cout << "row: " << id << ", " << value << ", " << size << std::endl; + std::cout << "row: " << id << ", " << (value ? value : "") << ", " << size << std::endl; } } catch (std::exception& e) @@ -396,6 +396,9 @@ catch (std::exception& e) } ``` +The `const char*` conversion returns `nullptr` for SQL `NULL`, so check the pointer before streaming it. +The pointer refers to the current row; copy the text if it must outlive the row. + `Statement` also provides a `RowIterator`, so the loop above can be written as a range-based `for`: ```C++ @@ -405,7 +408,7 @@ for (auto&& row : query) const char* value = row.getColumn(1); int size = row.getColumn(2); - std::cout << "row: " << id << ", " << value << ", " << size << std::endl; + std::cout << "row: " << id << ", " << (value ? value : "") << ", " << size << std::endl; } ``` diff --git a/examples/example1/main.cpp b/examples/example1/main.cpp index 83a62b92..483c7695 100644 --- a/examples/example1/main.cpp +++ b/examples/example1/main.cpp @@ -171,7 +171,7 @@ int main() { // Demonstrates how to get some typed column value (and the equivalent explicit call) const int id = query.getColumn(0); // = query.getColumn(0).getInt(); - //const char* pvalue = query.getColumn(1); // = query.getColumn(1).getText(); + //const char* pvalue = query.getColumn(1); // = query.getColumn(1).getText(nullptr); const std::string value = query.getColumn(1); // = query.getColumn(1).getText(); const int bytes = query.getColumn(1).size(); // .getColumn(1).getBytes(); const double weight = query.getColumn(2); // = query.getColumn(2).getInt(); diff --git a/include/SQLiteCpp/Statement.h b/include/SQLiteCpp/Statement.h index 2f4647d9..95649d24 100644 --- a/include/SQLiteCpp/Statement.h +++ b/include/SQLiteCpp/Statement.h @@ -650,11 +650,15 @@ class SQLITECPP_API Statement Column getColumn(const char* apName) const; /** - * @brief Return an instance of T constructed from copies of the first N columns + * @brief Construct T from the first N columns of the current result row. * * Can be used to access the data of the current row of result when applicable, * while the executeStep() method returns true. * + * @warning Pointer and view members (e.g. const char* or std::string_view) refer to SQLite-owned memory. + * Copy their data before stepping, resetting, or finalizing the statement, or a conversion + * that could invalidate the underlying buffer. + * * Throw an exception if there is no row to return a Column from: * - if provided column count is out of bound * - before any executeStep() call From 527a10c7326a489b74116ad6d0b17fe9db063f12 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?S=C3=A9bastien=20Rombauts?= Date: Sat, 24 Oct 2026 18:27:54 +0200 Subject: [PATCH 2/2] docs: record nullable text usage clarification Link the documentation follow-up to PR #613. --- CHANGELOG.md | 1 + 1 file changed, 1 insertion(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index fd30b507..160514e7 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -21,6 +21,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 - Make column type constants usable in constant expressions (ABI change) (#609) - Restrict CMake package compatibility to the same major version (#610) - Preserve SQL NULL as nullptr in implicit `const char*` conversions; use `getText()` for the old fallback (#612) +- Clarify nullable text examples and borrowed result lifetimes (#613) ### Removed