Glaze

One of the fastest JSON libraries in the world. Glaze reads and writes from object memory, simplifying interfaces and offering incredible performance.

Glaze also supports:

• BEVE (binary efficient versatile encoding)
• CSV (comma separated value)

With compile time reflection for MSVC, Clang, and GCC!

• Read/write aggregate initializable structs without writing any metadata or macros!
• See example on Compiler Explorer

Highlights

• Pure, compile time reflection for structs
• JSON RFC 8259 compliance with UTF-8 validation
• Standard C++ library support
• Header only
• Direct to memory serialization/deserialization
• Compile time maps with constant time lookups and perfect hashing
• Powerful wrappers to modify read/write behavior (Wrappers)
• Use your own custom read/write functions (Custom Read/Write)
• Handle unknown keys in a fast and flexible manner
• Direct memory access through JSON pointer syntax
• Binary data through the same API for maximum performance
• No exceptions (compiles with -fno-exceptions)
  • If you desire helpers that throw for cleaner syntax see Glaze Exceptions
• No runtime type information necessary (compiles with -fno-rtti)
• Rapid error handling with short circuiting
• JSON-RPC 2.0 support
• JSON Schema generation
• Extremely portable, uses carefully optimized SWAR (SIMD Within A Register) for broad compatibility
• Partial Read and Partial Write support
• CSV Reading/Writing
• Much more!

See DOCS for more documentation.

Performance

Performance test code available here

Performance caveats: simdjson and yyjson are great, but they experience major performance losses when the data is not in the expected sequence or any keys are missing (the problem grows as the file size increases, as they must re-iterate through the document).

Also, simdjson and yyjson do not support automatic escaped string handling, so if any of the currently non-escaped strings in this benchmark were to contain an escape, the escapes would not be handled.

ABC Test shows how simdjson has poor performance when keys are not in the expected sequence:

Binary Performance

Tagged binary specification: BEVE

JSON size: 670 bytes

BEVE size: 611 bytes

*BEVE packs more efficiently than JSON, so transporting the same data is even faster.

Example

Your struct will automatically get reflected! No metadata is required by the user.

struct my_struct
{
  int i = 287;
  double d = 3.14;
  std::string hello = "Hello World";
  std::array<uint64_t, 3> arr = { 1, 2, 3 };
  std::map<std::string, int> map{{"one", 1}, {"two", 2}};
};

JSON (prettified)

{
   "i": 287,
   "d": 3.14,
   "hello": "Hello World",
   "arr": [
      1,
      2,
      3
   ],
   "map": {
      "one": 1,
      "two": 2
   }
}

Write JSON

my_struct s{};
std::string buffer = glz::write_json(s).value_or("error");

or

my_struct s{};
std::string buffer{};
auto ec = glz::write_json(s, buffer);
if (ec) {
  // handle error
}

Read JSON

std::string buffer = R"({"i":287,"d":3.14,"hello":"Hello World","arr":[1,2,3],"map":{"one":1,"two":2}})";
auto s = glz::read_json<my_struct>(buffer);
if (s) // check std::expected
{
  s.value(); // s.value() is a my_struct populated from buffer
}

or

std::string buffer = R"({"i":287,"d":3.14,"hello":"Hello World","arr":[1,2,3],"map":{"one":1,"two":2}})";
my_struct s{};
auto ec = glz::read_json(s, buffer); // populates s from buffer
if (ec) {
  // handle error
}

Read/Write From File

auto ec = glz::read_file_json(obj, "./obj.json", std::string{});
auto ec = glz::write_file_json(obj, "./obj.json", std::string{});

[!IMPORTANT]

The file name (2nd argument), must be null terminated.

Compiler/System Support

• Requires C++23
• Only tested on 64bit systems, but should run on 32bit systems
• Only supports little-endian systems

Actions build and test with Clang (15+), MSVC (2022), and GCC (12+) on apple, windows, and linux.

Glaze seeks to maintain compatibility with the latest three versions of GCC and Clang, as well as the latest version of MSVC and Apple Clang.

MSVC Compiler Flags

Glaze requires a C++ standard conformant pre-processor, which requires the /Zc:preprocessor flag when building with MSVC.

How To Use Glaze

FetchContent

include(FetchContent)

FetchContent_Declare(
  glaze
  GIT_REPOSITORY https://github.com/stephenberry/glaze.git
  GIT_TAG main
  GIT_SHALLOW TRUE
)

FetchContent_MakeAvailable(glaze)

target_link_libraries(${PROJECT_NAME} PRIVATE glaze::glaze)

Conan

• Included in Conan Center

find_package(glaze REQUIRED)

target_link_libraries(main PRIVATE glaze::glaze)

build2

• Available on cppget

import libs = libglaze%lib{glaze}

Arch Linux

• AUR packages: glaze and glaze-git

See this Example Repository for how to use Glaze in a new project

See FAQ for Frequently Asked Questions

Explicit Metadata

If you want to specialize your reflection then you can optionally write the code below:

This metadata is also necessary for non-aggregate initializable structs.

template <>
struct glz::meta<my_struct> {
   using T = my_struct;
   static constexpr auto value = object(
      &T::i,
      &T::d,
      &T::hello,
      &T::arr,
      &T::map
   );
};

Local Glaze Meta

Glaze also supports metadata provided within its associated class:

struct my_struct
{
  int i = 287;
  double d = 3.14;
  std::string hello = "Hello World";
  std::array<uint64_t, 3> arr = { 1, 2, 3 };
  std::map<std::string, int> map{{"one", 1}, {"two", 2}};
  
  struct glaze {
     using T = my_struct;
     static constexpr auto value = glz::object(
        &T::i,
        &T::d,
        &T::hello,
        &T::arr,
        &T::map
     );
  };
};

Custom Key Names or Unnamed Types

When you define Glaze metadata, objects will automatically reflect the non-static names of your member object pointers. However, if you want custom names or you register lambda functions or wrappers that do not provide names for your fields, you can optionally add field names in your metadata.

Example of custom names:

template <>
struct glz::meta<my_struct> {
   using T = my_struct;
   static constexpr auto value = object(
      "integer", &T::i,
      "double", &T::d,
      "string", &T::hello,
      "array", &T::arr,
      "my map", &T::map
   );
};

Each of these strings is optional and can be removed for individual fields if you want the name to be reflected.

Names are required for:

• static constexpr member variables
• Wrappers
• Lambda functions

Custom Read/Write

Custom reading and writing can be achieved through the powerful to_json/from_json specialization approach, which is described here: custom-serialization.md. However, this only works for user defined types.

For common use cases or cases where a specific member variable should have special reading and writing, you can use glz::custom to register read/write member functions, std::functions, or lambda functions.

See an example:

struct custom_encoding
{
   uint64_t x{};
   std::string y{};
   std::array<uint32_t, 3> z{};
   
   void read_x(const std::string& s) {
      x = std::stoi(s);
   }
   
   uint64_t write_x() {
      return x;
   }
   
   void read_y(const std::string& s) {
      y = "hello" + s;
   }
   
   auto& write_z() {
      z[0] = 5;
      return z;
   }
};

template <>
struct glz::meta<custom_encoding>
{
   using T = custom_encoding;
   static constexpr auto value = object("x", custom<&T::read_x, &T::write_x>, //
                                        "y", custom<&T::read_y, &T::y>, //
                                        "z", custom<&T::z, &T::write_z>);
};

suite custom_encoding_test = [] {
   "custom_reading"_test = [] {
      custom_encoding obj{};
      std::string s = R"({"x":"3","y":"world","z":[1,2,3]})";
      expect(!glz::read_json(obj, s));
      expect(obj.x == 3);
      expect(obj.y == "helloworld");
      expect(obj.z == std::array<uint32_t, 3>{1, 2, 3});
   };
   
   "custom_writing"_test = [] {
      custom_encoding obj{};
      std::string s = R"({"x":"3","y":"world","z":[1,2,3]})";
      expect(!glz::read_json(obj, s));
      std::string out{};
      expect(not glz::write_json(obj, out));
      expect(out == R"({"x":3,"y":"helloworld","z":[5,2,3]})");
   };
};

Object Mapping

When using member pointers (e.g. &T::a) the C++ class structures must match the JSON interface. It may be desirable to map C++ classes with differing layouts to the same object interface. This is accomplished through registering lambda functions instead of member pointers.

template <>
struct glz::meta<Thing> {
   static constexpr auto value = object(
      "i", [](auto&& self) -> auto& { return self.subclass.i; }
   );
};

The value self passed to the lambda function will be a Thing object, and the lambda function allows us to make the subclass invisible to the object interface.

Lambda functions by default copy returns, therefore the auto& return type is typically required in order for glaze to write to memory.

Note that remapping can also be achieved through pointers/references, as glaze treats values, pointers, and references in the same manner when writing/reading.

Value Types

A class can be treated as an underlying value as follows:

struct S {
  int x{};
};

template <>
struct glz::meta<S> {
  static constexpr auto value{ &S::x };
};

or using a lambda:

template <>
struct glz::meta<S> {
  static constexpr auto value = [](auto& self) -> auto& { return self.x; };
};

Error Handling

Glaze is safe to use with untrusted messages. Errors are returned as error codes, typically within a glz::expected, which behaves just like a std::expected.

Glaze works to short circuit error handling, which means the parsing exits very rapidly if an error is encountered.

To generate more helpful error messages, call format_error:

auto pe = glz::read_json(obj, buffer);
if (pe) {
  std::string descriptive_error = glz::format_error(pe, buffer);
}

This test case:

{"Hello":"World"x, "color": "red"}

Produces this error:

1:17: expected_comma
   {"Hello":"World"x, "color": "red"}
                   ^

Denoting that x is invalid here.

Input Buffer (Null) Termination

A non-const std::string is recommended for input buffers, as this allows Glaze to improve performance with temporary padding and the buffer will be null terminated.

JSON

By default the option null_terminated is set to true and null-terminated buffers must be used when parsing JSON. The option can be turned off with a small loss in performance, which allows non-null terminated buffers:

constexpr glz::opts options{.null_terminated = false};
auto ec = glz::read<options>(value, buffer); // read in a non-null terminated buffer

BEVE

Null-termination is not required when parsing BEVE (binary). It makes no difference in performance.

CSV

[!WARNING]

Currently, null_terminated = false is not valid for CSV parsing and buffers must be null terminated.

Type Support

Array Types

Array types logically convert to JSON array values. Concepts are used to allow various containers and even user containers if they match standard library interfaces.

• glz::array (compile time mixed types)
• std::tuple (compile time mixed types)
• std::array
• std::vector
• std::deque
• std::list
• std::forward_list
• std::span