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
Binary Performance
Tagged binary specification: BEVE
Metric | Roundtrip Time (s) | Write (MB/s) | Read (MB/s) |
---|---|---|---|
Raw performance | 0.44 | 3168 | 2350 |
Equivalent JSON data* | 0.44 | 3474 | 2577 |
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.
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
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
);
};
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.
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
std::set
std::unordered_set
Object Types
Object types logically convert to JSON object values, such as maps. Like JSON, Glaze treats object definitions as unordered maps. Therefore the order of an object layout does not have to match the same binary sequence in C++.
glz::object
(compile time mixed types)std::map
std::unordered_map
std::pair
(enables dynamic keys in stack storage)
std::pair
is handled as an object with a single key and value, but whenstd::pair
is used in an array, Glaze concatenates the pairs into a single object.std::vector<std::pair<...>>
will serialize as a single object. If you don’t want this behavior set the compile time option.concatenate = false
.
Variants
std::variant
See Variant Handling for more information.
Nullable Types
std::unique_ptr
std::shared_ptr
std::optional
Nullable types may be allocated by valid input or nullified by the null
keyword.
std::unique_ptr<int> ptr{};
std::string buffer{};
expect(not glz::write_json(ptr, buffer));
expect(buffer == "null");
expect(not glz::read_json(ptr, "5"));
expect(*ptr == 5);
buffer.clear();
expect(not glz::write_json(ptr, buffer));
expect(buffer == "5");
expect(not glz::read_json(ptr, "null"));
expect(!bool(ptr));
Enums
By default enums will be written and read in integer form. No glz::meta
is necessary if this is the desired behavior.
However, if you prefer to use enums as strings in JSON, they can be registered in the glz::meta
as follows:
enum class Color { Red, Green, Blue };
template <>
struct glz::meta<Color> {
using enum Color;
static constexpr auto value = enumerate(Red,
Green,
Blue
);
};
In use:
Color color = Color::Red;
std::string buffer{};
glz::write_json(color, buffer);
expect(buffer == "\"Red\"");
Prettify JSON
Formatted JSON can be written out directly via a compile time option:
auto ec = glz::write<glz::opts{.prettify = true}>(obj, buffer);
Or, JSON text can be formatted with the glz::prettify_json
function:
std::string buffer = R"({"i":287,"d":3.14,"hello":"Hello World","arr":[1,2,3]})");
auto beautiful = glz::prettify_json(buffer);
beautiful
is now:
{
"i": 287,
"d": 3.14,
"hello": "Hello World",
"arr": [
1,
2,
3
]
}
Minify JSON
To write minified JSON:
auto ec = glz::write_json(obj, buffer); // default is minified
To minify JSON text call:
std::string minified = glz::minify_json(buffer);
Minified JSON Reading
If you wish require minified JSON or know your input will always be minified, then you can gain a little more performance by using the compile time option .minified = true
.
auto ec = glz::read<glz::opts{.minified = true}>(obj, buffer);
Logging JSON
Sometimes you just want to write out JSON structures on the fly as efficiently as possible. Glaze provides tuple-like structures that allow you to stack allocate structures to write out JSON with high speed. These structures are named glz::obj
for objects and glz::arr
for arrays.
Below is an example of building an object, which also contains an array, and writing it out.
auto obj = glz::obj{"pi", 3.14, "happy", true, "name", "Stephen", "arr", glz::arr{"Hello", "World", 2}};
std::string s{};
expect(not glz::write_json(obj, s));
expect(s == R"({"pi":3.14,"happy":true,"name":"Stephen","arr":["Hello","World",2]})");
This approach is significantly faster than
glz::json_t
for generic JSON. But, may not be suitable for all contexts.
Merge
glz::merge
allows the user to merge multiple JSON object types into a single object.
glz::obj o{"pi", 3.141};
std::map<std::string_view, int> map = {{"a", 1}, {"b", 2}, {"c", 3}};
auto merged = glz::merge{o, map};
std::string s{};
glz::write_json(merged, s); // will write out a single, merged object
// s is now: {"pi":3.141,"a":0,"b":2,"c":3}
glz::merge
stores references to lvalues to avoid copies
Generic JSON
See Generic JSON for glz::json_t
.
glz::json_t json{};
std::string buffer = R"([5,"Hello World",{"pi":3.14}])";
glz::read_json(json, buffer);
assert(json[2]["pi"].get<double>() == 3.14);
Raw Buffer Performance
Glaze is just about as fast writing to a std::string
as it is writing to a raw char buffer. If you have sufficiently allocated space in your buffer you can write to the raw buffer, as shown below, but it is not recommended.
glz::read_json(obj, buffer);
const auto n = glz::write_json(obj, buffer.data()).value_or(0);
buffer.resize(n);
Compile Time Options
The glz::opts
struct defines compile time optional settings for reading/writing.
Instead of calling glz::read_json(...)
, you can call glz::read<glz::opts{}>(...)
and customize the options.
For example: glz::read<glz::opts{.error_on_unknown_keys = false}>(...)
will turn off erroring on unknown keys and simple skip the items.
glz::opts
can also switch between formats:
glz::read<glz::opts{.format = glz::binary}>(...)
->glz::read_binary(...)
glz::read<glz::opts{.format = glz::json}>(...)
->glz::read_json(...)
Skip
It can be useful to acknowledge a keys existence in an object to prevent errors, and yet the value may not be needed or exist in C++. These cases are handled by registering a glz::skip
type with the meta data.
struct S {
int i{};
};
template <>
struct glz::meta<S> {
static constexpr auto value = object("key_to_skip", skip{}, &S::i);
};
std::string buffer = R"({"key_to_skip": [1,2,3], "i": 7})";
S s{};
glz::read_json(s, buffer);
// The value [1,2,3] will be skipped
expect(s.i == 7); // only the value i will be read into
Hide
Glaze is designed to help with building generic APIs. Sometimes a value needs to be exposed to the API, but it is not desirable to read in or write out the value in JSON. This is the use case for glz::hide
.
glz::hide
hides the value from JSON output while still allowing API (and JSON pointer) access.
struct hide_struct {
int i = 287;
double d = 3.14;
std::string hello = "Hello World";
};
template <>
struct glz::meta<hide_struct> {
using T = hide_struct;
static constexpr auto value = object(&T::i, //
&T::d, //
"hello", hide{&T::hello});
};
hide_struct s{};
auto b = glz::write_json(s);
expect(b == R"({"i":287,"d":3.14})"); // notice that "hello" is hidden from the output
Quoted Numbers
You can parse quoted JSON numbers directly to types like double
, int
, etc. by utilizing the glz::quoted
wrapper.
struct A {
double x;
std::vector<uint32_t> y;
};
template <>
struct glz::meta<A> {
static constexpr auto value = object("x", glz::quoted_num<&A::x>, "y", glz::quoted_num<&A::y>;
};
{
"x": "3.14",
"y": ["1", "2", "3"]
}
The quoted JSON numbers will be parsed directly into the double
and std::vector<uint32_t>
. The glz::quoted
function works for nested objects and arrays as well.
More Features
Data Recorder
Command Line Interface Menu
JSON Include System
JSON Pointer Syntax
JSON-RPC 2.0
JSON Schema
Shared Library API
Tagged Binary Messages
Thread Pool
Time Trace Profiling
- Output performance profiles to JSON and visualize using Perfetto
Wrappers
Extensions
See the ext
directory for extensions.