Implement nullable reflected fields

Author: jkalias

CMakeLists.txt

@@ -22,7 +22,12 @@ FetchContent_Declare(
   googletest
   URL https://github.com/google/googletest/archive/refs/tags/release-1.12.1.zip
 )
-FetchContent_MakeAvailable(googletest)
+FetchContent_Declare(
+  functional_cpp
+  URL https://github.com/jkalias/functional_cpp/archive/refs/tags/1.1.1.zip
+  SOURCE_SUBDIR src
+)
+FetchContent_MakeAvailable(googletest functional_cpp)
 
 # Set compiler settings based on the current platform
 if(CMAKE_HOST_UNIX)

README.md

@@ -133,8 +133,17 @@ Supported field macros:
 | `std::wstring` | `MEMBER_TEXT(name)` |
 | `bool` | `MEMBER_BOOL(name)` |
 | `sqlite_reflection::TimePoint` | `MEMBER_DATETIME(name)` |
+| `fcpp::optional_t<int64_t>` | `MEMBER_INT_NULLABLE(name)` |
+| `fcpp::optional_t<double>` | `MEMBER_REAL_NULLABLE(name)` |
+| `fcpp::optional_t<std::wstring>` | `MEMBER_TEXT_NULLABLE(name)` |
+| `fcpp::optional_t<bool>` | `MEMBER_BOOL_NULLABLE(name)` |
+| `fcpp::optional_t<sqlite_reflection::TimePoint>` | `MEMBER_DATETIME_NULLABLE(name)` |
 | member function declaration | `FUNC(signature)` |
 
+Nullable macros store SQL `NULL` as an empty optional and bind an empty optional back as SQL `NULL`; present optional values round-trip using the same storage class as their non-nullable counterparts, so `NULL`, an empty string, and numeric/boolean zero remain distinguishable after fetch. The optional type comes from [`functional_cpp`](https://github.com/jkalias/functional_cpp): under C++17 and later `fcpp::optional_t<T>` aliases `std::optional<T>`, while C++11 builds use the library fallback. Use `IsNull(&T::field)` and `IsNotNull(&T::field)` predicates for null checks. Value predicates such as `Equal(&T::nullable_field, value)` compare against a present contained value; pass the contained `T` value, not an optional.
+
+**Schema nullability caveat.** Newly created tables now declare non-nullable reflected fields as `NOT NULL` and omit `NOT NULL` for nullable fields. Because initialization uses `CREATE TABLE IF NOT EXISTS`, existing database files keep their previous column definitions until you recreate or migrate those tables, just like the `AUTOINCREMENT` caveat below.
+
 **Layout constraint.** Reflectable records must be simple, standard-layout structs: no base
 classes, no virtual functions, no virtual/multiple inheritance. Member access is computed from
 `offsetof`/pointer-to-member byte offsets, which are only well-defined for such types; a struct

include/query_predicates.h

@@ -42,6 +42,7 @@ struct REFLECTION_EXPORT SqlValue {
     bool bool_value;
     double real_value;
     std::string text_value;
+    bool is_null;
 };
 
 /// The base class of all WHERE predicates used in SQLite queries
@@ -103,13 +104,20 @@ class REFLECTION_EXPORT QueryPredicate : public QueryPredicateBase {
         : QueryPredicate(fn, value, symbol,
                          [&](void* v, SqliteStorageClass storage_class) { return GetSqlValue(v, storage_class); }) {}
 
+    template <typename T, typename R>
+    QueryPredicate(fcpp::optional_t<R> T::* fn, R value, const std::string& symbol)
+        : QueryPredicate(fn, fcpp::optional_t<R>(value), symbol, [&](void* v, SqliteStorageClass storage_class) {
+              return GetOptionalSqlValue(v, storage_class);
+          }) {}
+
     QueryPredicate(const std::string& symbol, const std::string& member_name, const SqlValue& value)
         : symbol_(symbol), member_name_(member_name), value_(value) {}
 
     /// Returns the value used for the current query, against which the struct member
     /// (defined from the pointer-to-member function) will be compared. The value needs
     /// to be type-erased, so that the header file is not bloated with unnecessary implementation details
     virtual SqlValue GetSqlValue(void* v, SqliteStorageClass storage_class) const;
+    virtual SqlValue GetOptionalSqlValue(void* v, SqliteStorageClass storage_class) const;
 
     /// The symbol used for the comparison, for example "=" for equality
     std::string symbol_;
@@ -122,6 +130,47 @@ class REFLECTION_EXPORT QueryPredicate : public QueryPredicateBase {
     SqlValue value_;
 };
 
+/// A wrapper for an empty predicate, used to fetch all elements of an SQLite table
+class REFLECTION_EXPORT NullPredicate : public QueryPredicateBase {
+public:
+    template <typename T, typename R>
+    NullPredicate(R T::* fn, const std::string& symbol) : symbol_(symbol) {
+        auto record = GetRecordFromTypeId(typeid(T).name());
+        auto offset = OffsetFromStart(fn);
+        for (auto i = 0; i < record.member_metadata.size(); ++i) {
+            if (record.member_metadata[i].offset == offset) {
+                member_name_ = record.member_metadata[i].name;
+                return;
+            }
+        }
+        throw std::runtime_error("No registered member of '" + record.name +
+                                 "' matches the given pointer-to-member (type id: " + typeid(T).name() + ")");
+    }
+
+    std::string Evaluate() const override;
+    std::vector<SqlValue> Bindings() const override;
+    QueryPredicateBase* Clone() const override;
+
+protected:
+    NullPredicate(const std::string& symbol, const std::string& member_name)
+        : symbol_(symbol), member_name_(member_name) {}
+
+    std::string symbol_;
+    std::string member_name_;
+};
+
+class REFLECTION_EXPORT IsNull final : public NullPredicate {
+public:
+    template <typename T, typename R>
+    explicit IsNull(R T::* fn) : NullPredicate(fn, "IS NULL") {}
+};
+
+class REFLECTION_EXPORT IsNotNull final : public NullPredicate {
+public:
+    template <typename T, typename R>
+    explicit IsNotNull(R T::* fn) : NullPredicate(fn, "IS NOT NULL") {}
+};
+
 /// A wrapper for an empty predicate, used to fetch all elements of an SQLite table
 class REFLECTION_EXPORT EmptyPredicate final : public QueryPredicateBase {
 public:
@@ -137,6 +186,9 @@ class REFLECTION_EXPORT Equal final : public QueryPredicate {
     template <typename T, typename R>
     explicit Equal(R T::* fn, R value) : QueryPredicate(fn, value, "=") {}
 
+    template <typename T, typename R>
+    explicit Equal(fcpp::optional_t<R> T::* fn, R value) : QueryPredicate(fn, value, "=") {}
+
     template <typename T>
     explicit Equal(int64_t T::* fn, int value) : Equal(fn, (int64_t)value) {}
 
@@ -151,6 +203,9 @@ class REFLECTION_EXPORT Unequal final : public QueryPredicate {
     template <typename T, typename R>
     explicit Unequal(R T::* fn, R value) : QueryPredicate(fn, value, "!=") {}
 
+    template <typename T, typename R>
+    explicit Unequal(fcpp::optional_t<R> T::* fn, R value) : QueryPredicate(fn, value, "!=") {}
+
     template <typename T>
     explicit Unequal(int64_t T::* fn, int value) : Unequal(fn, (int64_t)value) {}
 
@@ -167,6 +222,12 @@ class REFLECTION_EXPORT Like final : public QueryPredicate {
         : QueryPredicate(fn, value, "LIKE",
                          [&](void* v, SqliteStorageClass storage_class) { return GetSqlValue(v, storage_class); }) {}
 
+    template <typename T, typename R>
+    explicit Like(fcpp::optional_t<R> T::* fn, R value)
+        : QueryPredicate(fn, fcpp::optional_t<R>(value), "LIKE", [&](void* v, SqliteStorageClass storage_class) {
+              return GetOptionalSqlValue(v, storage_class);
+          }) {}
+
     template <typename T>
     explicit Like(int64_t T::* fn, int value) : Like(fn, (int64_t)value) {}
 
@@ -189,6 +250,12 @@ class REFLECTION_EXPORT GreaterThan final : public QueryPredicate {
 
     template <typename T>
     explicit GreaterThan(double T::* fn, double value) : QueryPredicate(fn, value, ">") {}
+
+    template <typename T>
+    explicit GreaterThan(fcpp::optional_t<int64_t> T::* fn, int64_t value) : QueryPredicate(fn, value, ">") {}
+
+    template <typename T>
+    explicit GreaterThan(fcpp::optional_t<double> T::* fn, double value) : QueryPredicate(fn, value, ">") {}
 };
 
 /// A wrapper for a comparison predicate, for which the value of the
@@ -203,6 +270,12 @@ class REFLECTION_EXPORT GreaterThanOrEqual final : public QueryPredicate {
 
     template <typename T>
     explicit GreaterThanOrEqual(double T::* fn, double value) : QueryPredicate(fn, value, ">=") {}
+
+    template <typename T>
+    explicit GreaterThanOrEqual(fcpp::optional_t<int64_t> T::* fn, int64_t value) : QueryPredicate(fn, value, ">=") {}
+
+    template <typename T>
+    explicit GreaterThanOrEqual(fcpp::optional_t<double> T::* fn, double value) : QueryPredicate(fn, value, ">=") {}
 };
 
 /// A wrapper for a comparison predicate, for which the value of the
@@ -217,6 +290,12 @@ class REFLECTION_EXPORT SmallerThan final : public QueryPredicate {
 
     template <typename T>
     explicit SmallerThan(double T::* fn, double value) : QueryPredicate(fn, value, "<") {}
+
+    template <typename T>
+    explicit SmallerThan(fcpp::optional_t<int64_t> T::* fn, int64_t value) : QueryPredicate(fn, value, "<") {}
+
+    template <typename T>
+    explicit SmallerThan(fcpp::optional_t<double> T::* fn, double value) : QueryPredicate(fn, value, "<") {}
 };
 
 /// A wrapper for a comparison predicate, for which the value of the
@@ -231,6 +310,12 @@ class REFLECTION_EXPORT SmallerThanOrEqual final : public QueryPredicate {
 
     template <typename T>
     explicit SmallerThanOrEqual(double T::* fn, double value) : QueryPredicate(fn, value, "<=") {}
+
+    template <typename T>
+    explicit SmallerThanOrEqual(fcpp::optional_t<int64_t> T::* fn, int64_t value) : QueryPredicate(fn, value, "<=") {}
+
+    template <typename T>
+    explicit SmallerThanOrEqual(fcpp::optional_t<double> T::* fn, double value) : QueryPredicate(fn, value, "<=") {}
 };
 
 /// A wrapper of a compound predicate, which combines two other predicates,

include/reflection.h

@@ -33,6 +33,7 @@
 #include <typeinfo>
 #include <vector>
 
+#include "optional.h"
 #include "reflection_export.h"
 
 /// The storage class in an SQLite column for a given member of a struct, for which reflection is enabled
@@ -47,11 +48,12 @@ struct REFLECTION_EXPORT Reflection {
     /// This holds the metadata of a given struct member
     class MemberMetadata {
     public:
-        MemberMetadata(const std::string& _name, SqliteStorageClass _storage_class, size_t _offset)
+        MemberMetadata(const std::string& _name, SqliteStorageClass _storage_class, size_t _offset, bool _nullable = false)
             : name(_name),
               storage_class(_storage_class),
               sqlite_column_name(ToSqliteColumnName(_storage_class)),
-              offset(_offset) {}
+              offset(_offset),
+              nullable(_nullable) {}
 
         /// The struct variable member name, as defined in the source code
         std::string name;
@@ -66,6 +68,9 @@ struct REFLECTION_EXPORT Reflection {
         /// The memory offset in bytes of this member from the struct's start, including any padding bits
         size_t offset;
 
+        /// Whether this member is represented by optional_t<T> and may carry SQL NULL
+        bool nullable;
+
     private:
         /// Helper for conversion between member storage class and SQLite column name
         static const char* ToSqliteColumnName(const SqliteStorageClass storage_class) {
@@ -113,7 +118,9 @@ size_t OffsetFromStart(R T::* fn) {
 #define CAT(A, B) CAT_NOEXPAND(A, B)
 
 #define DEFINE_MEMBER(R, T) \
-    reflectable.member_metadata.push_back(Reflection::MemberMetadata(STR(R), T, offsetof(struct REFLECTABLE, R)));
+    reflectable.member_metadata.push_back(Reflection::MemberMetadata(STR(R), T, offsetof(struct REFLECTABLE, R), false));
+#define DEFINE_MEMBER_NULLABLE(R, T) \
+    reflectable.member_metadata.push_back(Reflection::MemberMetadata(STR(R), T, offsetof(struct REFLECTABLE, R), true));
 
 /// A singleton object which holds all reflectable structs, and is guaranteed to be
 /// instantiated before main.cpp starts
@@ -167,6 +174,11 @@ struct REFLECTABLE_DLL_EXPORT REFLECTABLE {
 #define MEMBER_TEXT(R) MEMBER_DECLARE(std::wstring, R)
 #define MEMBER_DATETIME(R) MEMBER_DECLARE(sqlite_reflection::TimePoint, R)
 #define MEMBER_BOOL(R) MEMBER_DECLARE(bool, R)
+#define MEMBER_INT_NULLABLE(R) MEMBER_DECLARE(fcpp::optional_t<int64_t>, R)
+#define MEMBER_REAL_NULLABLE(R) MEMBER_DECLARE(fcpp::optional_t<double>, R)
+#define MEMBER_TEXT_NULLABLE(R) MEMBER_DECLARE(fcpp::optional_t<std::wstring>, R)
+#define MEMBER_DATETIME_NULLABLE(R) MEMBER_DECLARE(fcpp::optional_t<sqlite_reflection::TimePoint>, R)
+#define MEMBER_BOOL_NULLABLE(R) MEMBER_DECLARE(fcpp::optional_t<bool>, R)
 #define FUNC(SIGNATURE)
     FIELDS
 #undef MEMBER_DECLARE
@@ -175,6 +187,11 @@ struct REFLECTABLE_DLL_EXPORT REFLECTABLE {
 #undef MEMBER_TEXT
 #undef MEMBER_DATETIME
 #undef MEMBER_BOOL
+#undef MEMBER_INT_NULLABLE
+#undef MEMBER_REAL_NULLABLE
+#undef MEMBER_TEXT_NULLABLE
+#undef MEMBER_DATETIME_NULLABLE
+#undef MEMBER_BOOL_NULLABLE
 #undef FUNC
     int64_t id;
 
@@ -184,13 +201,23 @@ struct REFLECTABLE_DLL_EXPORT REFLECTABLE {
 #define MEMBER_TEXT(R)
 #define MEMBER_DATETIME(R)
 #define MEMBER_BOOL(R)
+#define MEMBER_INT_NULLABLE(R)
+#define MEMBER_REAL_NULLABLE(R)
+#define MEMBER_TEXT_NULLABLE(R)
+#define MEMBER_DATETIME_NULLABLE(R)
+#define MEMBER_BOOL_NULLABLE(R)
 #define FUNC(SIGNATURE) SIGNATURE;
     FIELDS
 #undef MEMBER_INT
 #undef MEMBER_REAL
 #undef MEMBER_TEXT
 #undef MEMBER_DATETIME
 #undef MEMBER_BOOL
+#undef MEMBER_INT_NULLABLE
+#undef MEMBER_REAL_NULLABLE
+#undef MEMBER_TEXT_NULLABLE
+#undef MEMBER_DATETIME_NULLABLE
+#undef MEMBER_BOOL_NULLABLE
 #undef FUNC
 };
 
@@ -232,13 +259,23 @@ static std::string CAT(Register, REFLECTABLE)() {
 #define MEMBER_TEXT(R) DEFINE_MEMBER(R, SqliteStorageClass::kText)
 #define MEMBER_DATETIME(R) DEFINE_MEMBER(R, SqliteStorageClass::kDateTime)
 #define MEMBER_BOOL(R) DEFINE_MEMBER(R, SqliteStorageClass::kBool)
+#define MEMBER_INT_NULLABLE(R) DEFINE_MEMBER_NULLABLE(R, SqliteStorageClass::kInt)
+#define MEMBER_REAL_NULLABLE(R) DEFINE_MEMBER_NULLABLE(R, SqliteStorageClass::kReal)
+#define MEMBER_TEXT_NULLABLE(R) DEFINE_MEMBER_NULLABLE(R, SqliteStorageClass::kText)
+#define MEMBER_DATETIME_NULLABLE(R) DEFINE_MEMBER_NULLABLE(R, SqliteStorageClass::kDateTime)
+#define MEMBER_BOOL_NULLABLE(R) DEFINE_MEMBER_NULLABLE(R, SqliteStorageClass::kBool)
 #define FUNC(SIGNATURE)
         FIELDS
 #undef MEMBER_INT
 #undef MEMBER_REAL
 #undef MEMBER_TEXT
 #undef MEMBER_DATETIME
 #undef MEMBER_BOOL
+#undef MEMBER_INT_NULLABLE
+#undef MEMBER_REAL_NULLABLE
+#undef MEMBER_TEXT_NULLABLE
+#undef MEMBER_DATETIME_NULLABLE
+#undef MEMBER_BOOL_NULLABLE
 #undef FUNC
     }
     return name;

src/CMakeLists.txt

@@ -25,6 +25,8 @@ source_group("internal" FILES ${HEADERS_INTERNAL})
 
 # Set Properties->General->Configuration Type to Dynamic Library (.dll/.so/.dylib)
 add_library(${LIBNAME} SHARED ${HEADERS} ${HEADERS_INTERNAL} ${SOURCES})
+target_link_libraries(${LIBNAME} PUBLIC fcpp)
+target_include_directories(${LIBNAME} PUBLIC ${functional_cpp_SOURCE_DIR}/include)
 
 if(CMAKE_HOST_UNIX AND NOT CMAKE_HOST_APPLE)
 target_link_libraries(${LIBNAME} PUBLIC tbb dl)