Json Namespace Reference

Enumerations

enum  SerializationFormat { Compact , Pretty , MessagePack }
 Describes format of serialized Json object. More...
 

Functions

template<typename TSource , typename TDest >
bool getValue (const TSource &source, TDest &dest)
 Copies a Json data value to a variable, but only if it exists. More...
 
template<typename TSource , typename TDest >
bool getValueChanged (const TSource &source, TDest &dest)
 Copies a Json data value to a variable, but only if it exists and its value has changed. More...
 
SerializationFormat operator++ (SerializationFormat &fmt)
 
template<typename TSource >
size_t measure (const TSource &source, SerializationFormat format=JSON_FORMAT_DEFAULT)
 Compute the size of a serialized Json object for a specified format. More...
 
template<typename TSource , typename TDestination >
size_t serialize (const TSource &source, TDestination &destination, SerializationFormat format=JSON_FORMAT_DEFAULT)
 Write a Json object in a specified format. More...
 
template<typename TSource , typename TPrint >
std::enable_if< std::is_base_of< Print, TPrint >::value, size_t >::type serialize (const TSource &source, TPrint *destination, SerializationFormat format=JSON_FORMAT_DEFAULT)
 Write a Json object in a specified format. More...
 
template<typename TSource >
size_t serialize (const TSource &source, char *buffer, size_t bufferSize, SerializationFormat format=JSON_FORMAT_DEFAULT)
 Write a Json object in a specified format. More...
 
template<typename TSource >
size_t serialize (const TSource &source, CString &output, SerializationFormat format=JSON_FORMAT_DEFAULT)
 
template<typename TSource >
String serialize (const TSource &source, SerializationFormat format=JSON_FORMAT_DEFAULT)
 Serialize a Json object in a specified format, returning it in a String object. More...
 
template<typename TSource >
bool saveToFile (const TSource &source, const String &filename, SerializationFormat format=JSON_FORMAT_DEFAULT)
 Save a Json object to a file in a specified format. More...
 
template<typename TInput >
bool deserializeInternal (JsonDocument &doc, TInput &input, SerializationFormat format=JSON_FORMAT_DEFAULT)
 
template<typename TInput >
bool deserialize (JsonDocument &doc, TInput &input, SerializationFormat format=JSON_FORMAT_DEFAULT)
 Read a JsonDocument from formatted data. More...
 
template<typename TInput >
std::enable_if<!std::is_base_of< Stream, TInput >::value, bool >::type deserialize (JsonDocument &doc, TInput *input, SerializationFormat format=JSON_FORMAT_DEFAULT)
 Read a JsonDocument from formatted data. More...
 
template<typename TStream >
std::enable_if< std::is_base_of< Stream, TStream >::value, bool >::type deserialize (JsonDocument &doc, TStream *input, SerializationFormat format=JSON_FORMAT_DEFAULT)
 Read a JsonDocument from formatted data. More...
 
template<typename TInput >
bool deserialize (JsonDocument &doc, TInput *input, size_t inputSize, SerializationFormat format=JSON_FORMAT_DEFAULT)
 Read a JsonDocument from formatted data. More...
 
template<>
bool deserialize (JsonDocument &doc, CString &input, SerializationFormat format)
 
bool loadFromFile (JsonDocument &doc, const String &filename, SerializationFormat format=JSON_FORMAT_DEFAULT)
 Parses the contents of a serialized file into a JsonDocument object. More...
 

Enumeration Type Documentation

◆ SerializationFormat

Describes format of serialized Json object.

Enumerator
Compact 

Compact JSON format.

Pretty 

Prettified JSON format, with spaces and line breaks.

MessagePack 

Message Pack (compact binary) format.

Function Documentation

◆ deserialize() [1/5]

template<>
bool Json::deserialize ( JsonDocument &  doc,
CString input,
SerializationFormat  format 
)
inline

◆ deserialize() [2/5]

template<typename TInput >
bool Json::deserialize ( JsonDocument &  doc,
TInput &  input,
SerializationFormat  format = JSON_FORMAT_DEFAULT 
)

Read a JsonDocument from formatted data.

Parameters
docDocument to store the decoded file
inputWhere to get data from (see notes)
formatFormat of the data
Return values
booltrue on success, false on error
Note
Supported read-only input types:
    Stream&
    String&
    const String&
    const FlashString&
String& is always read-only. If you wish to deserialize content in-situ, use:
    Json:: deserialize(doc, str.begin(), str.length(), format)
Don't forget to keep str in scope until you're finished with doc.

◆ deserialize() [3/5]

template<typename TInput >
std::enable_if<!std::is_base_of<Stream, TInput>::value, bool>::type Json::deserialize ( JsonDocument &  doc,
TInput *  input,
SerializationFormat  format = JSON_FORMAT_DEFAULT 
)

Read a JsonDocument from formatted data.

Parameters
docDocument to store the decoded file
inputWhere to get data from (see notes)
formatFormat of the data
Return values
booltrue on success, false on error
Note
Supported writeable input types (content will be modified in-situ):
    char*
Supported read-only input types:
    const char*
    const __FlashStringHelper*
    const FlashString*

◆ deserialize() [4/5]

template<typename TInput >
bool Json::deserialize ( JsonDocument &  doc,
TInput *  input,
size_t  inputSize,
SerializationFormat  format = JSON_FORMAT_DEFAULT 
)

Read a JsonDocument from formatted data.

Parameters
docDocument to store the decoded file
inputWhere to get data from (see notes)
inputSizeMaximum number of bytes to read from input
formatFormat of the data
Return values
booltrue on success, false on error
Note
Supported writeable input types (content will be modified in-situ):
    char*, size_t
Supported read-only input types:
    const char*, size_t
    const __FlashStringHelper*, size_t

◆ deserialize() [5/5]

template<typename TStream >
std::enable_if<std::is_base_of<Stream, TStream>::value, bool>::type Json::deserialize ( JsonDocument &  doc,
TStream *  input,
SerializationFormat  format = JSON_FORMAT_DEFAULT 
)

Read a JsonDocument from formatted data.

Parameters
docDocument to store the decoded file
inputWhere to get data from (see notes)
formatFormat of the data
Return values
booltrue on success, false on error
Note
Supports stream pointers (Stream and inherited classes) This function can be safely used with null pointers

◆ deserializeInternal()

template<typename TInput >
bool Json::deserializeInternal ( JsonDocument &  doc,
TInput &  input,
SerializationFormat  format = JSON_FORMAT_DEFAULT 
)

◆ getValue()

template<typename TSource , typename TDest >
bool Json::getValue ( const TSource &  source,
TDest &  dest 
)

Copies a Json data value to a variable, but only if it exists.

Parameters
sourceTypically provided from JsonObject[key], JsonDocument[key] or JsonVariant[key] call
destVariable to store value, unchanged if data is null
Return values
booltrue if value exists and was written to value
Note
Use to perform existence check before assignment, without requiring additional containsKey call or temporary variant. Example:
JsonDocument doc;
...
String value1;
if(!Json::getValue(doc["key1"], value1)) {
    // Perform required action when value1 doesn't exist, such as initialising defaults
}
Where a simple default is required, use the | operator. Examples:
String value1 = doc["key1"].as<const char*> | "default value";
int value2  = doc["key2] | -1;

◆ getValueChanged()

template<typename TSource , typename TDest >
bool Json::getValueChanged ( const TSource &  source,
TDest &  dest 
)

Copies a Json data value to a variable, but only if it exists and its value has changed.

Parameters
sourceTypically provided from JsonObject[key], JsonDocument[key] or JsonVariant[key] call
destVariable to store value, unchanged if data is null
Return values
booltrue if value exists and has changed, value updated

◆ loadFromFile()

bool Json::loadFromFile ( JsonDocument &  doc,
const String filename,
SerializationFormat  format = JSON_FORMAT_DEFAULT 
)
inline

Parses the contents of a serialized file into a JsonDocument object.

Parameters
docDocument to store the decoded file
filenameName of file to create, will always be overwritten
formatFormat of the data to be parsed
Return values
booltrue on success, false if the file couldn't be read or there was a parsing error

◆ measure()

template<typename TSource >
size_t Json::measure ( const TSource &  source,
SerializationFormat  format = JSON_FORMAT_DEFAULT 
)

Compute the size of a serialized Json object for a specified format.

Parameters
sourceJsonDocument, JsonArray, JsonObject or JsonVariant
formatSerialization format
Return values
size_tNumber of bytes that would be written when the document is serialized

◆ operator++()

SerializationFormat Json::operator++ ( SerializationFormat fmt)
inline

◆ saveToFile()

template<typename TSource >
bool Json::saveToFile ( const TSource &  source,
const String filename,
SerializationFormat  format = JSON_FORMAT_DEFAULT 
)

Save a Json object to a file in a specified format.

Parameters
sourceJsonDocument, JsonArray, JsonObject, JsonVariant
filenameName of file to create, will always be overwritten
formatSerialization format to use when writing
Return values
booltrue on success, false if the write failed

◆ serialize() [1/5]

template<typename TSource >
size_t Json::serialize ( const TSource &  source,
char *  buffer,
size_t  bufferSize,
SerializationFormat  format = JSON_FORMAT_DEFAULT 
)

Write a Json object in a specified format.

Parameters
sourceJsonDocument, JsonArray, JsonObject or JsonVariant
bufferBuffer for output data
bufferSizeSize of buffer
formatSerialization format to use when writing
Return values
size_tThe number of bytes written

◆ serialize() [2/5]

template<typename TSource >
size_t Json::serialize ( const TSource &  source,
CString output,
SerializationFormat  format = JSON_FORMAT_DEFAULT 
)

◆ serialize() [3/5]

template<typename TSource >
String Json::serialize ( const TSource &  source,
SerializationFormat  format = JSON_FORMAT_DEFAULT 
)

Serialize a Json object in a specified format, returning it in a String object.

Parameters
sourceJsonDocument, JsonArray, JsonObject or JsonVariant
formatSerialization format to use when writing
Return values
StringThe serialized data

◆ serialize() [4/5]

template<typename TSource , typename TDestination >
size_t Json::serialize ( const TSource &  source,
TDestination &  destination,
SerializationFormat  format = JSON_FORMAT_DEFAULT 
)

Write a Json object in a specified format.

Parameters
sourceJsonDocument, JsonArray, JsonObject or JsonVariant
destinationWhere to write output (char[], Print& or String&)
formatSerialization format to use when writing
Return values
size_tThe number of bytes written

◆ serialize() [5/5]

template<typename TSource , typename TPrint >
std::enable_if<std::is_base_of<Print, TPrint>::value, size_t>::type Json::serialize ( const TSource &  source,
TPrint *  destination,
SerializationFormat  format = JSON_FORMAT_DEFAULT 
)

Write a Json object in a specified format.

Parameters
sourceJsonDocument, JsonArray, JsonObject or JsonVariant
destinationWhere to write output (Print*)
formatSerialization format to use when writing
Return values
size_tThe number of bytes written
Note
This variant provides support for stream pointers, with null check