Nullable Types¶

Glaze provides concepts to support nullable types, including raw pointers, smart pointers, and optional types. In order to serialize and parse your custom nullable type it should conform to the nullable_t concept:

template <class T>
concept nullable_t = !meta_value_t<T> && !str_t<T> && requires(T t) {
   bool(t);
   {
      *t
   };
};

Raw Pointers¶

Raw pointers (T*) are treated as nullable types in Glaze. They automatically conform to the nullable_t concept and have the following behavior:

JSON Serialization¶

When serializing standalone pointers: - Null pointers serialize to null - Non-null pointers serialize to the pointed-to value

int* ptr = nullptr;
std::string json;
glz::write_json(ptr, json);  // Results in: "null"

int value = 42;
ptr = &value;
glz::write_json(ptr, json);  // Results in: "42"

Struct Members¶

When pointers are members of structs, their behavior depends on the skip_null_members option:

With `skip_null_members = true` (default)¶

Null pointer members are omitted from the JSON output:

struct my_struct {
    int* ptr{};
    double value{3.14};
};

my_struct obj;
std::string json;
glz::write_json(obj, json);  // Results in: {"value":3.14}

int x = 10;
obj.ptr = &x;
glz::write_json(obj, json);  // Results in: {"ptr":10,"value":3.14}

With `skip_null_members = false`¶

Null pointer members are written as null:

constexpr auto opts = glz::opts{.skip_null_members = false};
my_struct obj;
std::string json;
glz::write<opts>(obj, json);  // Results in: {"ptr":null,"value":3.14}

Automatic Reflection Support¶

Raw pointers work seamlessly with Glaze's automatic reflection (pure reflection) - no explicit glz::meta specialization is required:

struct example {
    int* int_ptr{};
    std::string* str_ptr{};
    double value{};
};
// No glz::meta needed - automatic reflection handles pointer members correctly

Behavior Consistency¶

Raw pointers behave consistently with other nullable types like std::optional and std::shared_ptr: - They respect the skip_null_members option - Null values can be omitted or written as null - Non-null values serialize to their pointed-to data

[!WARNING]

When using raw pointers in structs, ensure the pointed-to data remains valid during serialization. Glaze does not manage the lifetime of pointed-to objects.

JSON Deserialization¶

When deserializing into raw pointers, Glaze has the following behavior:

Pre-allocated Pointers¶

If the pointer is already non-null, Glaze will read directly into the pointed-to object:

struct example {
   int x{}, y{}, z{};
};

example obj;
example* ptr = &obj;  // Pre-allocated

std::string json = R"({"x":1,"y":2,"z":3})";
glz::read_json(ptr, json);  // Works: reads into existing object
// obj.x == 1, obj.y == 2, obj.z == 3

Null Pointers (Default Behavior)¶

By default, Glaze refuses to allocate memory for null raw pointers during deserialization. This is a safety feature because: - Glaze would need to call new without knowing how the memory will be freed - This makes memory leaks easy to introduce accidentally

example* ptr = nullptr;
std::string json = R"({"x":1,"y":2,"z":3})";
auto ec = glz::read_json(ptr, json);
// ec == glz::error_code::invalid_nullable_read (fails by design)

Enabling Automatic Allocation with `allocate_raw_pointers`¶

If you need Glaze to allocate memory for null raw pointers, enable the allocate_raw_pointers option. This is useful when deserializing containers of pointers where pre-allocation isn't practical:

struct alloc_opts : glz::opts {
   bool allocate_raw_pointers = true;
};

// Single pointer
example* ptr = nullptr;
std::string json = R"({"x":1,"y":2,"z":3})";
auto ec = glz::read<alloc_opts{}>(ptr, json);
// ptr is now allocated with new and populated
// IMPORTANT: You must manually delete ptr when done!
delete ptr;

// Vector of pointers
std::vector<example*> vec;
std::string json_array = R"([{"x":1,"y":2,"z":3},{"x":4,"y":5,"z":6}])";
auto ec2 = glz::read<alloc_opts{}>(vec, json_array);
// vec contains 2 newly allocated pointers
// IMPORTANT: You must manually delete each pointer!
for (auto* p : vec) delete p;

[!CAUTION]

When using allocate_raw_pointers = true, you are responsible for managing the allocated memory. Glaze allocates with new but has no way to track or free the memory. Failure to properly delete allocated pointers will result in memory leaks.

This option works with all supported formats: JSON, BEVE, CBOR, and MSGPACK.

[!NOTE]

If you want to read into a nullable type then you must have a .reset() method or your type must be assignable from empty braces: value = {}. This allows Glaze to reset the value if "null" is parsed.

Nullable Value Types¶

In some cases a type may be like a std::optional, but also require an operator bool() that converts to the internal boolean. In these cases you can instead conform to the nullable_value_t concept:

// For optional like types that cannot overload `operator bool()`
template <class T>
concept nullable_value_t = !meta_value_t<T> && requires(T t) {
   t.value();
   {
      t.has_value()
   } -> std::convertible_to<bool>;
};