Adopt fcpp::vector in the public Database API

README.md

@@ -13,6 +13,7 @@ A C++ wrapper for SQLite that provides compile-time checked CRUD operations for
 - [Opening and closing the database](#opening-and-closing-the-database)
 - [Saving records](#saving-records)
 - [Fetching records](#fetching-records)
+- [Working with query results](#working-with-query-results)
 - [Updating records](#updating-records)
 - [Deleting records](#deleting-records)
 - [Date and time fields](#date-and-time-fields)
@@ -346,6 +347,38 @@ Available predicate helpers include:
 
 Predicate values are bound with SQLite prepared statements. Text payloads are treated as values, not SQL syntax.
 
+## Working with query results
+
+`FetchAll` and `Fetch` return an [`fcpp::vector<T>`](https://github.com/jkalias/functional_cpp)
+rather than a `std::vector<T>`, so functional operations can be chained directly on the result
+without wrapping it yourself:
+
+```c++
+// Full names of every adult, straight off the query result.
+const auto adult_names = db->FetchAll<Person>()
+    .filter([](const Person& p) { return p.age >= 18; })
+    .map<std::wstring>([](const Person& p) { return p.GetFullName(); });
+
+// Predicate-style checks are available too.
+const bool everyone_is_adult = db->FetchAll<Person>()
+    .all_of([](const Person& p) { return p.age >= 18; });
+```
+
+`fcpp::vector` also supports `map`, `all_of`/`any_of`/`none_of`, `sort`, `distinct`, `zip`, and lazy
+pipelines via `.lazy()`; see the [functional_cpp](https://github.com/jkalias/functional_cpp)
+documentation. The batch `Save`, `SaveAutoIncrement`, and `Update` overloads accept an
+`fcpp::vector<T>` as well.
+
+**Migration note.** Because the result type changed from `std::vector<T>` to `fcpp::vector<T>`:
+
+- `auto` call sites, range-`for` loops, indexing (`result[i]`), and `size()` are unaffected.
+- Code that binds a result to a `std::vector<T>` explicitly no longer compiles, because there is no
+  implicit conversion back. Iterate the result directly, keep it as `fcpp::vector` (or `auto`), or
+  construct a `std::vector` from its iterators: `std::vector<Person>(result.begin(), result.end())`.
+- Indexing is **always bounds-checked**, in release builds too: `result[i]` for an out-of-range `i`
+  calls `std::abort()` instead of being undefined behavior (unless the library is built with
+  `FCPP_NO_PRECONDITION_CHECKS`).
+
 ## Updating records
 
 Fetch or construct a record, change its fields, and pass it to `Update`. The `id` identifies the row to update.
@@ -363,7 +396,7 @@ Multiple records can be updated in one call:
 
 ```c++
 // Update each record in the vector by its id.
-std::vector<Person> people = db->FetchAll<Person>();
+auto people = db->FetchAll<Person>();  // fcpp::vector<Person>
 people[0].last_name = L"Rambo";
 people[1].age = 20;
 
@@ -494,6 +527,8 @@ You can also open the generated `build/sqlite-cpp-reflection.sln` in Visual Stud
 
 - CMake 3.14 or newer
 - A C++11-compatible compiler
+- [functional_cpp](https://github.com/jkalias/functional_cpp) for `fcpp::vector` (query results) and
+  `fcpp::optional_t` (nullable fields), header-only, fetched by CMake
 - GoogleTest for tests, fetched by CMake
 - SQLite, vendored in `src/sqlite3.c` and `src/internal/sqlite3.h`
 

include/database.h

@@ -32,6 +32,7 @@
 #include "queries.h"
 #include "query_predicates.h"
 #include "reflection.h"
+#include "vector.h"  // fcpp::vector, the functional container returned by the query API
 
 struct sqlite3;
 
@@ -66,19 +67,23 @@ class REFLECTION_EXPORT Database {
     Database& operator=(Database&&) = delete;
 
     /// Retrieves all entries of a given record from the database.
-    /// This corresponds to a SELECT query in the SQL syntax
+    /// This corresponds to a SELECT query in the SQL syntax.
+    /// The result is an fcpp::vector, so functional operations (filter/map/...) can be chained
+    /// directly on it; range-for, indexing and size() work as with a std::vector.
     template <typename T>
-    std::vector<T> FetchAll() const {
+    fcpp::vector<T> FetchAll() const {
         const auto type_id = typeid(T).name();
         const auto& record = GetRecord(type_id);
         EmptyPredicate empty;
         return FetchRecords<T>(record, &empty);
     }
 
     /// Retrieves all entries of a given record from the database, which match a given predicate.
-    /// This corresponds to a SELECT query in the SQL syntax
+    /// This corresponds to a SELECT query in the SQL syntax.
+    /// The result is an fcpp::vector, so functional operations (filter/map/...) can be chained
+    /// directly on it; range-for, indexing and size() work as with a std::vector.
     template <typename T>
-    std::vector<T> Fetch(const QueryPredicateBase* predicate) const {
+    fcpp::vector<T> Fetch(const QueryPredicateBase* predicate) const {
         const auto type_id = typeid(T).name();
         const auto& record = GetRecord(type_id);
         return FetchRecords<T>(record, predicate);
@@ -120,26 +125,43 @@ class REFLECTION_EXPORT Database {
     /// Saves multiple records iteratively in the database.
     /// This corresponds to an INSERT query in the SQL syntax
     template <typename T>
-    void Save(const std::vector<T>& models) {
+    void Save(const fcpp::vector<T>& models) {
         const auto type_id = typeid(T).name();
         const auto& record = GetRecord(type_id);
         for (const auto& model : models) {
             Save((void*)&model, record);
         }
     }
 
+    /// std::vector compatibility overload: copies into an fcpp::vector and forwards.
+    template <typename T>
+    void Save(const std::vector<T>& models) {
+        Save(fcpp::vector<T>(models));
+    }
+
     /// Saves multiple records iteratively in the database, letting the database assign their ids.
     /// The newly generated ids are written back into the passed-in models.
     /// This corresponds to an INSERT query in the SQL syntax
     template <typename T>
-    void SaveAutoIncrement(std::vector<T>& models) {
+    void SaveAutoIncrement(fcpp::vector<T>& models) {
         const auto type_id = typeid(T).name();
         const auto& record = GetRecord(type_id);
         for (auto& model : models) {
             model.id = SaveAutoIncrement((void*)&model, record);
         }
     }
 
+    /// std::vector compatibility overload: saves each record through the single-record overload, so
+    /// every generated id is written back into the caller's std::vector as soon as its row is
+    /// inserted. This preserves the ids of already-committed rows if a later row in the batch fails
+    /// (each insert commits independently), matching the pre-fcpp::vector behavior.
+    template <typename T>
+    void SaveAutoIncrement(std::vector<T>& models) {
+        for (auto& model : models) {
+            SaveAutoIncrement(model);
+        }
+    }
+
     /// Updates a given record in the database.
     /// This corresponds to an UPDATE query in the SQL syntax
     template <typename T>
@@ -152,14 +174,20 @@ class REFLECTION_EXPORT Database {
     /// Updates multiple records iteratively in the database.
     /// This corresponds to an UPDATE query in the SQL syntax
     template <typename T>
-    void Update(const std::vector<T>& models) {
+    void Update(const fcpp::vector<T>& models) {
         const auto type_id = typeid(T).name();
         const auto& record = GetRecord(type_id);
         for (const auto& model : models) {
             Update((void*)&model, record);
         }
     }
 
+    /// std::vector compatibility overload: copies into an fcpp::vector and forwards.
+    template <typename T>
+    void Update(const std::vector<T>& models) {
+        Update(fcpp::vector<T>(models));
+    }
+
     /// Deletes a given record from the database.
     /// This corresponds to an DELETE query in the SQL syntax
     template <typename T>
@@ -203,14 +231,14 @@ class REFLECTION_EXPORT Database {
     /// each matching row directly from the prepared statement into a newly constructed T -
     /// no intermediate string materialization of the result set
     template <typename T>
-    std::vector<T> FetchRecords(const Reflection& record, const QueryPredicateBase* predicate) const {
+    fcpp::vector<T> FetchRecords(const Reflection& record, const QueryPredicateBase* predicate) const {
         std::lock_guard<std::mutex> lock(db_mutex_);
         FetchRecordsQuery query(db_, record, predicate);
-        std::vector<T> models;
+        fcpp::vector<T> models;
         while (query.StepRow()) {
             T model;
             query.HydrateCurrentRow((void*)&model, record);
-            models.emplace_back(std::move(model));
+            models.insert_back(std::move(model));
         }
         return models;
     }

tests/functional_vector_test.cc

@@ -0,0 +1,165 @@
+// MIT License
+//
+// Copyright (c) 2026 Ioannis Kaliakatsos
+//
+// Permission is hereby granted, free of charge, to any person obtaining a copy
+// of this software and associated documentation files (the "Software"), to deal
+// in the Software without restriction, including without limitation the rights
+// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+// copies of the Software, and to permit persons to whom the Software is
+// furnished to do so, subject to the following conditions:
+//
+// The above copyright notice and this permission notice shall be included in all
+// copies or substantial portions of the Software.
+//
+// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+// SOFTWARE.
+
+#include <gtest/gtest.h>
+
+#include <string>
+#include <vector>
+
+#include "database.h"
+#include "person.h"
+#include "vector.h"
+
+using namespace sqlite_reflection;
+
+namespace {
+class FunctionalVectorTest : public ::testing::Test {
+    void SetUp() override {
+        Database::Initialize("");
+    }
+
+    void TearDown() override {
+        Database::Finalize();
+    }
+};
+
+// The whole point of the migration: a fetch result is an fcpp::vector, so functional operations
+// can be chained directly on it, without the caller wrapping the std::vector themselves.
+TEST_F(FunctionalVectorTest, FetchResultChainsFilterAndMap) {
+    const auto db = Database::Instance();
+    db->Save(std::vector<Person>{
+        {L"ada", L"lovelace", 36, true, 1},
+        {L"grace", L"hopper", 17, true, 2},
+        {L"alan", L"turing", 41, true, 3},
+    });
+
+    // filter() (mutating, returns vector&) then map<U>() (non-mutating) chained on the temporary
+    // returned by FetchAll(), exactly as advertised in the README.
+    const auto adult_names = db->FetchAll<Person>()
+                                 .filter([](const Person& p) { return p.age >= 18; })
+                                 .map<std::wstring>([](const Person& p) { return p.GetFullName(); });
+
+    ASSERT_EQ(2u, adult_names.size());
+    EXPECT_EQ(L"ada lovelace", adult_names[0]);
+    EXPECT_EQ(L"alan turing", adult_names[1]);
+}
+
+TEST_F(FunctionalVectorTest, FetchResultSupportsAllOfAnyOf) {
+    const auto db = Database::Instance();
+    db->Save(std::vector<Person>{
+        {L"ada", L"lovelace", 36, true, 1},
+        {L"grace", L"hopper", 17, true, 2},
+    });
+
+    const auto people = db->FetchAll<Person>();
+    EXPECT_TRUE(people.all_of([](const Person& p) { return p.age > 0; }));
+    EXPECT_FALSE(people.all_of([](const Person& p) { return p.age >= 18; }));
+    EXPECT_TRUE(people.any_of([](const Person& p) { return p.age < 18; }));
+    EXPECT_FALSE(people.any_of([](const Person& p) { return p.age > 100; }));
+}
+
+// range-for and indexing over a fetch result keep working as with a std::vector
+TEST_F(FunctionalVectorTest, FetchResultSupportsRangeForAndIndexing) {
+    const auto db = Database::Instance();
+    db->Save(std::vector<Person>{
+        {L"ada", L"lovelace", 36, true, 1},
+        {L"alan", L"turing", 41, true, 2},
+    });
+
+    const auto people = db->FetchAll<Person>();
+
+    int64_t total_age = 0;
+    for (const auto& person : people) {
+        total_age += person.age;
+    }
+    EXPECT_EQ(77, total_age);
+    EXPECT_EQ(L"ada", people[0].first_name);
+    EXPECT_EQ(L"alan", people[1].first_name);
+}
+
+// Batch Save/Update accept an fcpp::vector directly.
+TEST_F(FunctionalVectorTest, BatchSaveAndUpdateAcceptFcppVector) {
+    const auto db = Database::Instance();
+
+    fcpp::vector<Person> people;
+    people.insert_back({L"ada", L"lovelace", 36, true, 1}).insert_back({L"alan", L"turing", 41, true, 2});
+
+    db->Save(people);
+
+    auto fetched = db->FetchAll<Person>();
+    ASSERT_EQ(2u, fetched.size());
+    EXPECT_EQ(36, fetched[0].age);
+
+    people[0].age = 37;
+    db->Update(people);
+
+    fetched = db->FetchAll<Person>();
+    ASSERT_EQ(2u, fetched.size());
+    EXPECT_EQ(37, fetched[0].age);
+}
+
+// SaveAutoIncrement writes the generated ids back into the passed-in fcpp::vector.
+TEST_F(FunctionalVectorTest, SaveAutoIncrementWritesIdsBackIntoFcppVector) {
+    const auto db = Database::Instance();
+
+    fcpp::vector<Person> people;
+    people.insert_back({L"ada", L"lovelace", 36, true}).insert_back({L"alan", L"turing", 41, true});
+
+    db->SaveAutoIncrement(people);
+
+    EXPECT_EQ(1, people[0].id);
+    EXPECT_EQ(2, people[1].id);
+    EXPECT_EQ(2u, db->FetchAll<Person>().size());
+}
+
+// The std::vector compatibility overloads keep working for callers that still pass a std::vector.
+TEST_F(FunctionalVectorTest, StdVectorCompatibilityOverloadsStillWork) {
+    const auto db = Database::Instance();
+
+    std::vector<Person> people;
+    people.push_back({L"ada", L"lovelace", 36, true, 1});
+    people.push_back({L"alan", L"turing", 41, true, 2});
+
+    db->Save(people);
+    EXPECT_EQ(2u, db->FetchAll<Person>().size());
+
+    people[0].age = 37;
+    db->Update(people);
+    EXPECT_EQ(37, db->Fetch<Person>(1).age);
+}
+
+// The SaveAutoIncrement std::vector wrapper writes the generated ids back into the caller's
+// std::vector, just like the fcpp::vector overload.
+TEST_F(FunctionalVectorTest, SaveAutoIncrementStdVectorWrapperWritesIdsBack) {
+    const auto db = Database::Instance();
+
+    std::vector<Person> people;
+    people.push_back({L"ada", L"lovelace", 36, true});
+    people.push_back({L"alan", L"turing", 41, true});
+
+    db->SaveAutoIncrement(people);
+
+    EXPECT_EQ(1, people[0].id);
+    EXPECT_EQ(2, people[1].id);
+    EXPECT_EQ(2u, db->FetchAll<Person>().size());
+}
+}  // namespace