Skip to content

Compile Time Options

Glaze provides extensive compile time options to customize serialization/deserialization behavior. This document serves as a comprehensive reference for all available options.

Quick Reference Tables

The tables below list all compile time options, organized by category:

  • Core Options: Available in the default glz::opts struct
  • Inheritable Options: Must be added to a custom options struct (see How to Use Inheritable Options)
  • CSV Options: Available in glz::opts_csv

Core Options (glz::opts)

Option Default Description
uint32_t format JSON Format selector (JSON, BEVE, CSV, TOML, etc.)
bool null_terminated true Whether the input buffer is null terminated
bool comments false Support reading JSONC style comments
bool error_on_unknown_keys true Error when an unknown key is encountered
bool skip_null_members true Skip writing out members if their value is null
bool prettify false Write out prettified JSON
bool minified false Require minified input for faster read performance
char indentation_char ' ' Prettified JSON indentation character
uint8_t indentation_width 3 Prettified JSON indentation size
bool new_lines_in_arrays true Whether prettified arrays have new lines per element
bool error_on_missing_keys false Require all non-nullable keys to be present
bool quoted_num false Treat numbers as quoted or arrays as having quoted numbers
bool number false Treat string-like types as numbers
bool raw false Write string-like values without quotes
bool raw_string false Skip escape sequence encoding/decoding for strings
bool structs_as_arrays false Handle structs without keys (as arrays)
bool partial_read false Exit after reading the deepest structural object

Inheritable Options

These options are not in glz::opts by default. Add them to a custom options struct to use them.

Option Default Description
bool validate_skipped false Perform full validation on skipped values
bool validate_trailing_whitespace false Validate whitespace after parsing completes
bool bools_as_numbers false Read/write booleans as 1 and 0
bool write_member_functions false Serialize member function pointers in glz::meta (off by default for safety)
bool concatenate true Concatenate ranges of std::pair into single objects
bool allow_conversions true Allow type conversions in BEVE (e.g., double → float)
bool write_type_info true Write type info for meta objects in variants
bool append_arrays false Append to arrays instead of replacing contents
bool shrink_to_fit false Shrink dynamic containers after reading
bool error_on_const_read false Error when attempting to read into a const value
bool hide_non_invocable true Hide non-invocable members from cli_menu
bool escape_control_characters false Escape control characters as unicode sequences
float_precision float_max_write_precision full Maximum precision for writing floats
static constexpr std::string_view float_format (none) Format string for float output using std::format (C++23)
bool skip_null_members_on_read false Skip null values when reading (preserve existing value)
bool skip_self_constraint false Skip self_constraint validation during reading
bool assume_sufficient_buffer false Skip bounds checking for fixed-size buffers (caller guarantees space)
bool linear_search false Use linear key search instead of hash tables for smaller binary size
size_t max_string_length 0 Maximum string length when reading (0 = no limit)
size_t max_array_size 0 Maximum array size when reading (0 = no limit)
size_t max_map_size 0 Maximum map size when reading (0 = no limit)
bool allocate_raw_pointers false Allocate memory for null raw pointers during deserialization

CSV Options (glz::opts_csv)

For CSV format, use glz::opts_csv which provides CSV-specific defaults.

Option Default Description
uint32_t format CSV Format selector (fixed to CSV)
bool null_terminated true Whether the input buffer is null terminated
uint8_t layout rowwise Data layout: rowwise or colwise
bool use_headers true Read/write with column headers
bool raw_string false Skip escape sequence encoding/decoding
bool skip_header_row false Skip first row when reading
bool validate_rectangular false Ensure all rows have equal column counts

Notes: - layout: rowwise treats each row as a record; colwise uses columns (2D arrays are transposed on IO). - use_headers: when false, vectors of structs read/write without headers in declaration order. - skip_header_row: skip the first row during read (useful when ingesting headered CSV into headerless targets). - validate_rectangular: for 2D arrays, fail reads when row lengths differ (constraint_violated). - append_arrays: appends parsed values to existing containers when supported (add to custom opts struct). - Use as a template parameter: glz::read<glz::opts_csv{.layout = glz::colwise, .use_headers = false}>(...).

How to Use Inheritable Options

Glaze uses C++20 concepts to detect if an option exists. If an option is not present in your options struct, a default value is used. This allows you to create custom option structs with only the options you need.

Creating a Custom Options Struct

Inherit from glz::opts and add the options you need:

struct my_opts : glz::opts
{
   bool validate_trailing_whitespace = true;
   bool skip_self_constraint = true;
};

Using Custom Options

constexpr my_opts opts{};
auto ec = glz::read<opts>(obj, buffer);

Or specify base options inline:

// Set both a base option (prettify) and an inheritable option
struct my_write_opts : glz::opts {
   bool escape_control_characters = true;
};
glz::write<my_write_opts{.prettify = true, .escape_control_characters = true}>(obj, buffer);

How Detection Works

Glaze uses consteval functions to check for option existence at compile time:

consteval bool check_validate_trailing_whitespace(auto&& Opts) {
   if constexpr (requires { Opts.validate_trailing_whitespace; }) {
      return Opts.validate_trailing_whitespace;
   } else {
      return false; // Default value
   }
}

Option Details

Format & Parsing Options

format

Selects the serialization format. Built-in formats include: - glz::JSON (10) - JSON format - glz::BEVE (1) - Binary Efficient Versatile Encoding - glz::CSV (10000) - Comma Separated Values - glz::TOML (400) - Tom's Obvious Minimal Language - glz::NDJSON (100) - Newline Delimited JSON

null_terminated

When true (default), Glaze assumes input buffers are null-terminated, enabling certain optimizations. Set to false for non-null-terminated buffers with a small performance cost.

comments

Enable JSONC-style comment parsing (// and /* */).

minified

When true, assumes input JSON has no unnecessary whitespace. This skips all whitespace checking during parsing, providing faster performance and slightly smaller binary size. Will fail on prettified input with whitespace between tokens.

Validation Options

error_on_unknown_keys

When true (default), parsing fails if the JSON contains keys not present in your C++ struct. Set to false to silently skip unknown keys.

error_on_missing_keys

When true, parsing fails if required keys are missing from the JSON input. Works with skip_null_members = false to also require nullable members. Can be customized per-type using meta<T>::requires_key(key, is_nullable) function (see Field Validation).

validate_skipped

Performs full JSON validation on values that are skipped (unknown keys). Without this, Glaze only validates that skipped content is structurally valid.

validate_trailing_whitespace

Validates that content after the parsed value contains only valid whitespace.

skip_self_constraint

Skips self_constraint validation during deserialization. Useful for performance when data is known to be valid. See Wrappers for more on constraints.

error_on_const_read

When true, attempting to read into a const value produces an error. By default, const values are silently skipped.

assume_sufficient_buffer

When true, skips bounds checking for fixed-size buffers (std::array, std::span). Use this when you've pre-validated that the buffer is large enough, for maximum write performance. Has no effect on resizable buffers (std::string, std::vector) or raw pointers (char*).

struct fast_opts : glz::opts {
   bool assume_sufficient_buffer = true;
};

std::array<char, 8192> large_buffer;
auto result = glz::write<fast_opts{}>(obj, large_buffer);
// No bounds checking overhead - caller guarantees sufficient space

Output Control Options

skip_null_members

When true (default), null values are omitted from JSON output. This applies to nullable types like std::optional, std::shared_ptr, std::unique_ptr, and raw pointers (T*).

prettify

When true, outputs formatted JSON with indentation and newlines.

indentation_char / indentation_width

Control prettified output formatting. Default is 3 spaces per level.

new_lines_in_arrays

When true (default), prettified arrays have each element on its own line.

raw / raw_string

Control string quoting and escape sequence handling. Useful for embedding pre-formatted content.

escape_control_characters

When true, control characters (0x00-0x1F) are escaped as \uXXXX sequences. The default (false) does not escape these characters for performance and safety (embedding nulls can cause issues, especially with C APIs). Glaze will error when parsing non-escaped control characters per the JSON spec—this option allows writing them as escaped unicode to avoid such errors on re-read.

Performance Options

partial_read

Exits parsing after reading the deepest structural object. Useful for reading headers or partial documents.

append_arrays

When reading into arrays, appends new elements instead of replacing existing contents.

shrink_to_fit

Calls shrink_to_fit() on dynamic containers after reading to minimize memory usage.

Binary Size Options

When true, uses linear search for object key lookup instead of compile-time generated hash tables. This significantly reduces binary size (typically 40-50% smaller) at the cost of slightly slower parsing for objects with many fields.

struct small_opts : glz::opts {
   bool linear_search = true;
};

auto ec = glz::read<small_opts{}>(obj, buffer);

How it works:

By default, Glaze generates perfect hash tables at compile time for each struct type, enabling O(1) key lookup. This provides excellent runtime performance but increases binary size because: - Each struct type gets its own hash table stored in the binary - Jump tables are generated for field dispatch - Multiple template instantiations may be created for optimization

With linear_search = true: - Keys are matched using simple linear comparison (O(n) where n = number of fields) - Hash tables are not generated - Fold-expression dispatch replaces jump tables - Template instantiation bloat is reduced

When to use:

  • Embedded systems with limited flash/ROM
  • Applications where binary size matters more than peak parsing speed
  • Objects with few fields (< 10) where linear search has negligible overhead
  • Shipping smaller binaries to reduce download/install size

Trade-offs:

Aspect Default (hash) linear_search = true
Key lookup O(1) O(n)
Binary size Larger ~40-50% smaller
Parse speed Fastest Slightly slower for large objects
Compile time Longer Shorter

For objects with few fields, the performance difference is negligible. For objects with many fields (20+), hash-based lookup will be noticeably faster.

Type Handling Options

quoted_num

Treats numbers as quoted strings (e.g., "123" instead of 123).

number

Treats string-like types as unquoted numbers.

structs_as_arrays

Serializes/deserializes structs as JSON arrays (without keys), using field order.

bools_as_numbers

Reads/writes boolean values as 1 and 0 instead of true and false.

write_type_info

When true (default), includes type discriminator information for variant types.

concatenate

When true (default), ranges of std::pair are written as a single object with pairs as key-value entries.

allow_conversions

When true (default), BEVE allows implicit type conversions (e.g., reading a double into a float).

allocate_raw_pointers

When true, allows Glaze to allocate memory for null raw pointers during deserialization using new. By default (false), Glaze refuses to read into null raw pointers because it would need to allocate memory without any mechanism to free it, making memory leaks likely.

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

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

// Without the option, this fails with invalid_nullable_read
std::vector<example*> vec;
std::string json = R"([{"x":1,"y":2,"z":3}])";
auto ec = glz::read<alloc_opts{}>(vec, json);
// vec[0] is now allocated and populated

// IMPORTANT: You must manually delete allocated pointers
for (auto* p : vec) delete p;

[!CAUTION] When using this option, you are responsible for freeing the allocated memory. Glaze uses new to allocate but cannot track or delete the memory. Use smart pointers (std::unique_ptr, std::shared_ptr) when possible instead.

This option works with JSON, BEVE, CBOR, and MSGPACK formats. See Nullable Types for more details.

float_max_write_precision

Limits the precision used when writing floating-point numbers. Options: full, float32, float64, float128.

float_format

Formats all floating-point numbers using std::format syntax (C++23). This provides control over decimal places, scientific notation, and other formatting options.

struct format_opts : glz::opts
{
   static constexpr std::string_view float_format = "{:.2f}";
};

std::vector<double> values{3.14159, 2.71828, 1.41421};
std::string json = glz::write<format_opts{}>(values).value_or("error");
// Output: [3.14,2.72,1.41]

Common format specifiers: - {:.2f} - Fixed-point with 2 decimal places - {:.0f} - Fixed-point with no decimals (rounds) - {:.2e} - Scientific notation (lowercase) - {:.4g} - General format (auto-selects fixed or scientific)

[!NOTE] The format string is validated at compile time via std::format_string. Invalid format strings will cause compilation errors.

For per-member formatting control, see the glz::float_format wrapper.

See Also