JSON BinPack

Choosing the right format depends on your primary bottleneck (bandwidth vs. CPU/latency):

Use JSON BinPack when:

• Your primary goal is space efficiency (reducing payload size).
• You are transmitting data over unreliable or low-bandwidth connections (e.g., Mobile or IoT systems).
• You want to leverage existing JSON Schema definitions.
• You can trade more CPU cycles for better compression to improve network performance.

Consider alternatives (like FlatBuffers or Cap'n Proto) when:

• You require extreme runtime-efficiency.
• You need zero-copy serialization.
• You are performing intra-service or inter-process communication (IPC) where computation/latency is the bottleneck rather than network bandwidth.

JSON BinPack relies on the expressive constraint-based nature of JSON Schema.

• Encoding: You can encode free-form data and unknown fields as long as your JSON Schema definition is written to permit them (e.g., using additionalProperties).
• Deserialization: Deserializing data that does not match the provided JSON Schema definition is considered undefined behavior and will likely result in an exception being thrown.

The Encoder class is used to serialize sourcemeta::core::JSON documents into the JSON BinPack binary format. You initialize the Encoder with a Stream object and then call the write method, specifying the desired Encoding type.

To use the Encoder, you must provide a sourcemeta::core::JSON document and an Encoding constant that defines how the data should be packed.

#include <sourcemeta/jsonbinpack/runtime_encoder.h>

// Assuming 'stream' is a valid implementation of a Stream
sourcemeta::jsonbinpack::Encoder encoder(stream);

// 'document' is a sourcemeta::core::JSON object
// 'encoding' is a valid Encoding type from the specification
encoder.write(document, encoding);

Use the load function to convert a sourcemeta::core::JSON object into a sourcemeta::jsonbinpack::Encoding. This is the primary entry point for decoding JSON data into the BinPack format.

#include <sourcemeta/jsonbinpack/runtime.h>

auto encoding = sourcemeta::jsonbinpack::load(json_input);

The sourcemeta::jsonbinpack::InputStream class provides a specialized interface for reading BinPack-encoded data from a standard C++ input stream. It inherits from sourcemeta::core::BinaryReader and provides methods to consume common BinPack primitives like varints and UTF-8 strings.

To use it, instantiate an InputStream by passing a reference to a std::basic_istream configured with sourcemeta::core::JSON::Char and sourcemeta::core::JSON::CharTraits.

#include <sourcemeta/jsonbinpack/runtime_input_stream.h>
#include <fstream>

// Assuming a stream configured with sourcemeta::core::JSON traits
sourcemeta::jsonbinpack::InputStream input(my_istream);

// Example usage of primitives
std::uint64_t val = input.get_varint();
std::int64_t zigzag_val = input.get_varint_zigzag();
auto str = input.get_string_utf8(length);

The OutputStream class provides a specialized interface for writing JSON BinPack encoded data to a standard C++ output stream. It inherits from sourcemeta::core::BinaryWriter and is designed to work with std::basic_ostream using sourcemeta::core::JSON::Char and sourcemeta::core::JSON::CharTraits.

Use this class when you need to manually drive the encoding process into an existing stream using low-level primitives like varints and UTF-8 strings.

#include <sourcemeta/jsonbinpack/runtime_output_stream.h>
#include <iostream>

// Assuming a stream is already available
std::ostream my_stream;
// Initialize the OutputStream with the target stream
sourcemeta::jsonbinpack::OutputStream output_stream(my_stream);

// Use primitives to write data
output_stream.put_varint(42);
output_stream.put_string_utf8("example", 7);

The Decoder class is used to parse JSON BinPack binary data into sourcemeta::core::JSON objects. To use it, instantiate a Decoder with a Stream object representing your input source. You can then use the read method, passing an Encoding object to specify how the next chunk of data should be interpreted according to the JSON BinPack specification.

#include <sourcemeta/jsonbinpack/runtime_decoder.h>

// Assuming 'input_stream' is a valid sourcemeta::jsonbinpack::Stream
sourcemeta::jsonbinpack::Decoder decoder(input_stream);

// Read data using a specific encoding
auto json_data = decoder.read(some_encoding);

The OutputStream class provides the following methods for writing encoded data:

• put_varint(const std::uint64_t value): Writes an unsigned 64-bit integer using variable-length encoding.
• put_varint_zigzag(const std::int64_t value): Writes a signed 64-bit integer using ZigZag encoding followed by variable-length encoding.
• put_string_utf8(const sourcemeta::core::JSON::String &string, const std::uint64_t length): Writes a UTF-8 encoded string of the specified length.

auto put_varint(const std::uint64_t value) -> void;
auto put_varint_zigzag(const std::int64_t value) -> void;
auto put_string_utf8(const sourcemeta::core::JSON::String &string, const std::uint64_t length) -> void;

The read method is the primary entry point for extracting data from the binary stream. It takes a const Encoding &encoding as an argument and returns a sourcemeta::core::JSON object representing the decoded value.

auto read(const Encoding &encoding) -> sourcemeta::core::JSON;