Common-Use-Cases.md

Common Use Cases

• Include the right header
• Read any JSON file
• Parse any JSON string
• Serialise a JSON Value to a string
• Serialise with base64 strings for binary data
• Serialise a JSON Value to an ostream
• Create a Value with a JSON object

Include the right header

The convenience include <tao/json.hpp> will include the entire core library. Additionally, it might be useful to include <tao/json/contrib/traits.hpp> to add some commonly used Traits specialisations, mostly for containers and smart pointers.

#include <tao/json.hpp>
#include <tao/json/contrib/traits.hpp>

(To improve compile times, you can choose to directly use only some of the individual headers that it includes.)

Read any JSON file

const tao::json::value v = tao::json::from_file( "filename.json" );

Parse any JSON string

const tao::json::value v = tao::json::from_string( "{ \"a\": 1.0, \"b\": 2.0 }" );

Serialise a JSON Value to a string

We will assume that v is a valid JSON Value instance.

const std::string j = tao::json::to_string( v );

Passing a std::size_t as second argument enable pretty-printing mode with the given size as indent.

Passing a std::string as third argument uses the given string as line ending instead of the \n default.

Serialise with base64 strings for binary data

The JSON format does not allow for binary data. Binary data in Values needs to be converted into something else when serialising to JSON. This can be done on-the-fly with an Events Transformer like tao::json::events::binary_to_base64.

const std::string l = tao::json::to_string< tao::json::events::binary_to_base64 >( v );

Another similar common use case is to use a Transformer like tao::json::events::non_finite_to_null to convert non-finite floating-point values (not-a-number, infinity) to something that fits in the JSON data model.

See the Events interface documentation for all available Event Transformers.

Serialise a JSON Value to an ostream

tao::json::to_stream( std::cout, v );

The additional function and template arguments are just like for to_string().

using namespace tao::json;

to_stream< events::binary_to_base64, events::non_finite_to_null >( std::cout, v, 3, "\r\n" );

When no Events Transformers are needed the usual operator<< overloads can be used, too.

std::cout << v << std::endl;  // Compact.
std::cout << std::setw( 2 ) << v << std::endl;  // Pretty-printed with indent 2.

Create a Value with a JSON object

First possibility

Parse a string that represents a JSON object, see above.

This works similarly with files, and with strings and files in other supported formats.

Second possibility

Use the literal string operator to parse a literal string.

using namespace tao::json;

const auto v = "{ \"a\": 1.0, \"b\": 2.0 }"_json;

Third possibility

Use the std::initalizer_list<> constructor.

const tao::json::value v = {
   { "a", 1.0 },
   { "b", 2.0 }
};

Fourth possibility

Use the appropriate value member functions.

int main()
{
   tao::json::value v;
   v.emplace( "a", 1.0 );
   v.emplace( "b", 2.0 );
   return 0;
}

Note that v.emplace() will work both on values that already represent an Object and on values that are in state UNINITIALIZED or DISCARDED.

Fifth possibility

Use an Event Consumer to feed Events to a value.

int main()
{
   tao::json::events::to_value consumer;
   consumer.begin_object();
   consumer.key( "a" );
   consumer.number( 1.0 );
   consumer.member();
   consumer.key( "b" );
   consumer.number( 2.0 );
   consumer.member();
   consumer.end_object();
   const tao::json::value v = std::move( consumer.value );
   return 0;
}

Copyright (c) 2018-2023 Dr. Colin Hirsch and Daniel Frey