Clarify nullable text and getColumns() lifetimes

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
 

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 : "<NULL>") << ", " << 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 : "<NULL>") << ", " << size << std::endl;
 }
 ```
 

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();

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