nfx::json::Builder Class Reference

High-performance JSON builder with incremental construction API. More...

#include <nfx/json/Builder.h>

Classes
struct	Options
	Configuration options for Builder. More...

Public Member Functions
	Builder (Options options={ 0, 4096, false })
	Constructor with options.
Builder &	writeStartObject ()
	Start writing a JSON object.
Builder &	writeEndObject ()
	End writing a JSON object.
Builder &	writeStartArray ()
	Start writing a JSON array.
Builder &	writeEndArray ()
	End writing a JSON array.
Builder &	writeKey (std::string_view key)
	Write a property key before a nested object or array.
Builder &	writeRawJson (std::string_view rawJson)
	Write raw JSON string directly to output.
Builder &	write (std::string_view key, std::nullptr_t value)
	Write a null value property.
Builder &	write (std::string_view key, bool value)
	Write a boolean value property.
Builder &	write (std::string_view key, int value)
	Write an integer value property.
Builder &	write (std::string_view key, unsigned int value)
	Write an unsigned integer value property.
Builder &	write (std::string_view key, int64_t value)
	Write a 64-bit integer value property.
Builder &	write (std::string_view key, uint64_t value)
	Write an unsigned 64-bit integer value property.
Builder &	write (std::string_view key, float value)
	Write a float value property.
Builder &	write (std::string_view key, double value)
	Write a double value property.
Builder &	write (std::string_view key, std::string_view value)
	Write a string value property.
Builder &	write (std::string_view key, const char *value)
	Write a string value property.
Builder &	write (std::string_view key, const std::string &value)
	Write a string value property.
Builder &	write (std::string_view key, const Document &value)
	Write a Document value property.
Builder &	write (std::nullptr_t value)
	Write a null value in an array.
Builder &	write (bool value)
	Write a boolean value in an array.
Builder &	write (int value)
	Write an integer value in an array.
Builder &	write (unsigned int value)
	Write an unsigned integer value in an array.
Builder &	write (int64_t value)
	Write a 64-bit integer value in an array.
Builder &	write (uint64_t value)
	Write an unsigned 64-bit integer value in an array.
Builder &	write (float value)
	Write a float value in an array.
Builder &	write (double value)
	Write a double value in an array.
Builder &	write (std::string_view value)
	Write a string value in an array.
Builder &	write (const char *value)
	Write a string value in an array.
Builder &	write (const std::string &value)
	Write a string value in an array.
Builder &	write (const Document &value)
	Write a Document value in an array.
template<typename T>
std::enable_if_t< std::is_same_v< T, long > &&!std::is_same_v< long, int > &&!std::is_same_v< long, int64_t >, Builder & >	write (std::string_view key, T value)
	Write a long integer value property (SFINAE overload for platforms where long != int64_t).
template<typename T>
std::enable_if_t< std::is_same_v< T, unsigned long > &&!std::is_same_v< unsigned long, unsigned int > &&!std::is_same_v< unsigned long, uint64_t >, Builder & >	write (std::string_view key, T value)
	Write an unsigned long integer value property (SFINAE overload for platforms where unsigned long != uint64_t).
template<typename T>
std::enable_if_t< std::is_same_v< T, long long > &&!std::is_same_v< long long, int64_t >, Builder & >	write (std::string_view key, T value)
	Write a long long integer value property (SFINAE overload for platforms where long long != int64_t).
template<typename T>
std::enable_if_t< std::is_same_v< T, unsigned long long > &&!std::is_same_v< unsigned long long, uint64_t >, Builder & >	write (std::string_view key, T value)
	Write an unsigned long long integer value property (SFINAE overload for platforms where unsigned long long != uint64_t).
template<typename T>
std::enable_if_t< std::is_same_v< T, long > &&!std::is_same_v< long, int > &&!std::is_same_v< long, int64_t >, Builder & >	write (T value)
	Write a long integer value in an array (SFINAE overload for platforms where long != int64_t).
template<typename T>
std::enable_if_t< std::is_same_v< T, unsigned long > &&!std::is_same_v< unsigned long, unsigned int > &&!std::is_same_v< unsigned long, uint64_t >, Builder & >	write (T value)
	Write an unsigned long integer value in an array (SFINAE overload for platforms where unsigned long != uint64_t).
template<typename T>
std::enable_if_t< std::is_same_v< T, long long > &&!std::is_same_v< long long, int64_t >, Builder & >	write (T value)
	Write a long long integer value in an array (SFINAE overload for platforms where long long != int64_t).
template<typename T>
std::enable_if_t< std::is_same_v< T, unsigned long long > &&!std::is_same_v< unsigned long long, uint64_t >, Builder & >	write (T value)
	Write an unsigned long long integer value in an array (SFINAE overload for platforms where unsigned long long != uint64_t).
std::string	toString ()
	Get the constructed JSON string.
Builder &	reset ()
	Reset builder to initial state for reuse.
size_t	size () const noexcept
	Get current JSON string size.
bool	isEmpty () const noexcept
	Check if builder is empty.
Builder &	reserve (size_t capacity)
	Reserve buffer capacity.
std::string_view	toStringView () const noexcept
	Get non-destructive view of generated JSON.
size_t	capacity () const noexcept
	Get current buffer capacity.
size_t	depth () const noexcept
	Get current nesting depth.
bool	isValid () const noexcept
	Check if builder state is valid.
template<typename Container>
Builder &	writeArray (std::string_view key, const Container &values)
	Write a complete array from a STL container as object property.
template<typename Container>
Builder &	writeArray (const Container &values)
	Write a complete array from a STL container.

Detailed Description

High-performance JSON builder with incremental construction API.

Constructs JSON directly to string buffer without building DOM. Provides a fluent API for building JSON documents programmatically. Optimized with SSE2 SIMD for string escaping on supported platforms.

Example usage:

Builder builder;
builder.writeStartObject()
       .write("name", "John Doe")
       .write("age", 30)
       .writeEndObject();
std::string json = builder.toString();
// {"name":"John Doe","age":30}

Definition at line 67 of file Builder.h.

Constructor & Destructor Documentation

Builder()

nfx::json::Builder::Builder ( Options options = { 0, 4096, false } )

inlineexplicit

Constructor with options.

Parameters

options

Configuration options for the builder

Member Function Documentation

capacity()

size_t nfx::json::Builder::capacity ( ) const

inlinenodiscardnoexcept

Get current buffer capacity.

Returns

Allocated capacity of internal buffer in bytes

depth()

size_t nfx::json::Builder::depth ( ) const

inlinenodiscardnoexcept

Get current nesting depth.

Returns

Number of nested objects/arrays

Note

Returns 0 when at root level

isEmpty()

bool nfx::json::Builder::isEmpty ( ) const

inlinenodiscardnoexcept

Check if builder is empty.

Returns

true if no JSON has been written

isValid()

bool nfx::json::Builder::isValid ( ) const

inlinenodiscardnoexcept

Check if builder state is valid.

Returns

true if all opened objects/arrays have been closed

reserve()

Builder & nfx::json::Builder::reserve ( size_t capacity )

inline

Reserve buffer capacity.

Parameters

capacity

Minimum buffer size in bytes to reserve

Returns

Reference to this builder for method chaining

Note

Pre-allocating capacity avoids reallocations during construction of large JSON documents

reset()

Builder & nfx::json::Builder::reset ( )

inline

Reset builder to initial state for reuse.

Returns

Reference to this builder for method chaining

Note

Clears all buffered data and context stack, allowing builder reuse without reallocation

size()

size_t nfx::json::Builder::size ( ) const

inlinenodiscardnoexcept

Get current JSON string size.

Returns

Size of generated JSON in bytes

toString()

std::string nfx::json::Builder::toString ( )

inline

Get the constructed JSON string.

Returns

The complete JSON string

toStringView()

std::string_view nfx::json::Builder::toStringView ( ) const

inlinenodiscardnoexcept

Get non-destructive view of generated JSON.

Returns

String view to the internal buffer

Note

Does not invalidate the builder state, unlike toString()

write() [1/32]

Builder & nfx::json::Builder::write ( bool value )

inline

Write a boolean value in an array.

Parameters

value

Boolean value

Returns

Reference to this builder for method chaining

write() [2/32]

Builder & nfx::json::Builder::write ( const char * value )

inline

Write a string value in an array.

Parameters

value

C-string value

Returns

Reference to this builder for method chaining

write() [3/32]

Builder & nfx::json::Builder::write ( const Document & value )

inline

Write a Document value in an array.

Parameters

value

Document to serialize

Returns

Reference to this builder for method chaining

write() [4/32]

Builder & nfx::json::Builder::write ( const std::string & value )

inline

Write a string value in an array.

Parameters

value

String value

Returns

Reference to this builder for method chaining

write() [5/32]

Builder & nfx::json::Builder::write ( double value )

inline

Write a double value in an array.

Parameters

value

Double value

Returns

Reference to this builder for method chaining

write() [6/32]

Builder & nfx::json::Builder::write ( float value )

inline

Write a float value in an array.

Parameters

value

Float value

Returns

Reference to this builder for method chaining

write() [7/32]

Builder & nfx::json::Builder::write ( int value )

inline

Write an integer value in an array.

Parameters

value

Integer value

Returns

Reference to this builder for method chaining

write() [8/32]

Builder & nfx::json::Builder::write ( int64_t value )

inline

Write a 64-bit integer value in an array.

Parameters

value

64-bit integer value

Returns

Reference to this builder for method chaining

write() [9/32]

Builder & nfx::json::Builder::write ( std::nullptr_t value )

inline

Write a null value in an array.

Parameters

value

nullptr

Returns

Reference to this builder for method chaining

write() [10/32]

Builder & nfx::json::Builder::write ( std::string_view key, bool value )

inline

Write a boolean value property.

Parameters

key	Property key
value	Boolean value

Returns

Reference to this builder for method chaining

write() [11/32]

Builder & nfx::json::Builder::write ( std::string_view key, const char * value )

inline

Write a string value property.

Parameters

key	Property key
value	C-string value

Returns

Reference to this builder for method chaining

write() [12/32]

Builder & nfx::json::Builder::write ( std::string_view key, const Document & value )

inline

Write a Document value property.

Parameters

key	Property key
value	Document to serialize

Returns

Reference to this builder for method chaining

write() [13/32]

Builder & nfx::json::Builder::write ( std::string_view key, const std::string & value )

inline

Write a string value property.

Parameters

key	Property key
value	String value

Returns

Reference to this builder for method chaining

write() [14/32]

Builder & nfx::json::Builder::write ( std::string_view key, double value )

inline

Write a double value property.

Parameters

key	Property key
value	Double value

Returns

Reference to this builder for method chaining

write() [15/32]

Builder & nfx::json::Builder::write ( std::string_view key, float value )

inline

Write a float value property.

Parameters

key	Property key
value	Float value

Returns

Reference to this builder for method chaining

write() [16/32]

Builder & nfx::json::Builder::write ( std::string_view key, int value )

inline

Write an integer value property.

Parameters

key	Property key
value	Integer value

Returns

Reference to this builder for method chaining

write() [17/32]

Builder & nfx::json::Builder::write ( std::string_view key, int64_t value )

inline

Write a 64-bit integer value property.

Parameters

key	Property key
value	64-bit integer value

Returns

Reference to this builder for method chaining

write() [18/32]

Builder & nfx::json::Builder::write ( std::string_view key, std::nullptr_t value )

inline

Write a null value property.

Parameters

key	Property key
value	nullptr

Returns

Reference to this builder for method chaining

write() [19/32]

Builder & nfx::json::Builder::write ( std::string_view key, std::string_view value )

inline

Write a string value property.

Parameters

key	Property key
value	String value

Returns

Reference to this builder for method chaining

write() [20/32]

template<typename T>

std::enable_if_t< std::is_same_v< T, unsigned long long > &&!std::is_same_v< unsigned long long, uint64_t >, Builder & > nfx::json::Builder::write ( std::string_view key, T value )

inline

Write an unsigned long long integer value property (SFINAE overload for platforms where unsigned long long != uint64_t).

Parameters

key	Property key
value	Unsigned long long integer value

Returns

Reference to this builder for method chaining

write() [21/32]

template<typename T>

std::enable_if_t< std::is_same_v< T, long long > &&!std::is_same_v< long long, int64_t >, Builder & > nfx::json::Builder::write ( std::string_view key, T value )

inline

Write a long long integer value property (SFINAE overload for platforms where long long != int64_t).

Parameters

key	Property key
value	Long long integer value

Returns

Reference to this builder for method chaining

write() [22/32]

template<typename T>

std::enable_if_t< std::is_same_v< T, unsigned long > &&!std::is_same_v< unsigned long, unsigned int > &&!std::is_same_v< unsigned long, uint64_t >, Builder & > nfx::json::Builder::write ( std::string_view key, T value )

inline

Write an unsigned long integer value property (SFINAE overload for platforms where unsigned long != uint64_t).

Parameters

key	Property key
value	Unsigned long integer value

Returns

Reference to this builder for method chaining

write() [23/32]

template<typename T>

std::enable_if_t< std::is_same_v< T, long > &&!std::is_same_v< long, int > &&!std::is_same_v< long, int64_t >, Builder & > nfx::json::Builder::write ( std::string_view key, T value )

inline

Write a long integer value property (SFINAE overload for platforms where long != int64_t).

Parameters

key	Property key
value	Long integer value

Returns

Reference to this builder for method chaining

write() [24/32]

Builder & nfx::json::Builder::write ( std::string_view key, uint64_t value )

inline

Write an unsigned 64-bit integer value property.

Parameters

key	Property key
value	Unsigned 64-bit integer value

Returns

Reference to this builder for method chaining

write() [25/32]

Builder & nfx::json::Builder::write ( std::string_view key, unsigned int value )

inline

Write an unsigned integer value property.

Parameters

key	Property key
value	Unsigned integer value

Returns

Reference to this builder for method chaining

write() [26/32]

Builder & nfx::json::Builder::write ( std::string_view value )

inline

Write a string value in an array.

Parameters

value

String value

Returns

Reference to this builder for method chaining

write() [27/32]

template<typename T>

std::enable_if_t< std::is_same_v< T, unsigned long long > &&!std::is_same_v< unsigned long long, uint64_t >, Builder & > nfx::json::Builder::write ( T value )

inline

Write an unsigned long long integer value in an array (SFINAE overload for platforms where unsigned long long != uint64_t).

Parameters

value

Unsigned long long integer value

Returns

Reference to this builder for method chaining

write() [28/32]

template<typename T>

std::enable_if_t< std::is_same_v< T, long long > &&!std::is_same_v< long long, int64_t >, Builder & > nfx::json::Builder::write ( T value )

inline

Write a long long integer value in an array (SFINAE overload for platforms where long long != int64_t).

Parameters

value

Long long integer value

Returns

Reference to this builder for method chaining

write() [29/32]

template<typename T>

std::enable_if_t< std::is_same_v< T, unsigned long > &&!std::is_same_v< unsigned long, unsigned int > &&!std::is_same_v< unsigned long, uint64_t >, Builder & > nfx::json::Builder::write ( T value )

inline

Write an unsigned long integer value in an array (SFINAE overload for platforms where unsigned long != uint64_t).

Parameters

value

Unsigned long integer value

Returns

Reference to this builder for method chaining

write() [30/32]

template<typename T>

std::enable_if_t< std::is_same_v< T, long > &&!std::is_same_v< long, int > &&!std::is_same_v< long, int64_t >, Builder & > nfx::json::Builder::write ( T value )

inline

Write a long integer value in an array (SFINAE overload for platforms where long != int64_t).

Parameters

value

Long integer value

Returns

Reference to this builder for method chaining

write() [31/32]

Builder & nfx::json::Builder::write ( uint64_t value )

inline

Write an unsigned 64-bit integer value in an array.

Parameters

value

Unsigned 64-bit integer value

Returns

Reference to this builder for method chaining

write() [32/32]

Builder & nfx::json::Builder::write ( unsigned int value )

inline

Write an unsigned integer value in an array.

Parameters

value

Unsigned integer value

Returns

Reference to this builder for method chaining

writeArray() [1/2]

template<typename Container>

Builder & nfx::json::Builder::writeArray ( const Container & values )

inline

Write a complete array from a STL container.

Template Parameters

Container

STL container type (vector, list, set, etc.)

Parameters

values

Container of values to write as array

Returns

Reference to this builder for method chaining

Note

Automatically iterates container and writes each element

writeArray() [2/2]

template<typename Container>

Builder & nfx::json::Builder::writeArray ( std::string_view key, const Container & values )

inline

Write a complete array from a STL container as object property.

Template Parameters

Container

STL container type (vector, list, set, etc.)

Parameters

key	Property key
values	Container of values to write as array

Returns

Reference to this builder for method chaining

Note

Automatically iterates container and writes each element

writeEndArray()

Builder & nfx::json::Builder::writeEndArray ( )

inline

End writing a JSON array.

Returns

Reference to this builder for method chaining

Exceptions

std::runtime_error

if no matching writeStartArray

writeEndObject()

Builder & nfx::json::Builder::writeEndObject ( )

inline

End writing a JSON object.

Returns

Reference to this builder for method chaining

Exceptions

std::runtime_error

if no matching writeStartObject

writeKey()

Builder & nfx::json::Builder::writeKey ( std::string_view key )

inline

Write a property key before a nested object or array.

Parameters

key	Property key

Returns

Reference to this builder for method chaining

Note

Use this before writeStartObject() or writeStartArray() for nested structures

writeRawJson()

Builder & nfx::json::Builder::writeRawJson ( std::string_view rawJson )

inline

Write raw JSON string directly to output.

Parameters

rawJson

Raw JSON string to append

Returns

Reference to this builder for method chaining

writeStartArray()

Builder & nfx::json::Builder::writeStartArray ( )

inline

Start writing a JSON array.

Returns

Reference to this builder for method chaining

Exceptions

std::runtime_error

if called in invalid context

writeStartObject()

Builder & nfx::json::Builder::writeStartObject ( )

inline

Start writing a JSON object.

Returns

Reference to this builder for method chaining

Exceptions

std::runtime_error

if called in invalid context

---

The documentation for this class was generated from the following file:

• Builder.h