json/doc/Reference.md
2014-12-30 11:47:28 +01:00

4.5 KiB

Reference

Nomenclature

We use the term "JSON" when we mean the JavaScript Object Notation; that is, the file format. When we talk about the class implementing our library, we use "JSON" (typewriter font). Instances of this class are called "JSON values" to differentiate them from "JSON objects"; that is, unordered mappings, hashes, and whatnot.

Types and default values

This table describes how JSON values are mapped to C++ types.

JSON type value_type C++ type type alias default value
null value_type::null nullptr_t - nullptr
string value_type::string std::string JSON::string_t ""
number (integer) value_type::number int JSON::number_t 0
number (floating point) value_type::number_float double JSON::number_float_t 0.0
array value_type::array std::array<JSON> JSON::array_t {}
object value_type::object std::map<std::string, JSON> JSON::object_t {}

The second column list entries of an enumeration value_type which can be queried by calling type() on a JSON value. The column "C++ types" list the internal type that is used to represent the respective JSON value. The "type alias" column furthermore lists type aliases that are used in the JSON class to allow for more flexibility. The last column list the default value; that is, the value that is set if none is passed to the constructor or that is set if clear() is called.

Type conversions

There are only a few type conversions possible:

  • An integer number can be translated to a floating point number.
  • A floating point number can be translated to an integer number. Note the number is truncated and not rounded, ceiled or floored.
  • Any value (i.e., boolean, string, number, null) but JSON objects can be translated into an array. The result is a singleton array that consists of the value before.
  • Any other conversion will throw a std::logic_error exception.

When compatible, JSON values implicitly convert to std::string, int, double, JSON::array_t, and JSON::object_t. Furthermore, explicit type conversion is possible using the get<>() function with the aforementioned types.

Initialization

JSON values can be created from many literals and variable types:

JSON type literal/variable types examples
none null pointer literal, nullptr_t type, no value nullptr
boolean boolean literals, bool type, JSON::boolean_t type true, false
string string literal, char* type, std::string type, std::string&& rvalue reference, JSON::string_t type "Hello"
number (integer) integer literal, short int type, int type, JSON_number_t type 42
number (floating point) floating point literal, float type, double type, JSON::number_float_t type 3.141529
array initializer list whose elements are JSON values (or can be translated into JSON values using the rules above), std::vector<JSON> type, JSON::array_t type, JSON::array_t&& rvalue reference {1, 2, 3, true, "foo"}
object initializer list whose elements are pairs of a string literal and a JSON value (or can be translated into JSON values using the rules above), std::map<std::string, JSON> type, JSON::object_t type, JSON::object_t&& rvalue reference { {"key1", 42}, {"key2", false} }

Number types

JSON number format

The JSON specification explicitly does not define an internal number representation, but only the syntax of how numbers can be written down. Consequently, we would need to use the largest possible floating point number format (e.g., long double) to internally store JSON numbers.

However, this would be a waste of space, so we let the JSON parser decide which format to use: If the number can be precisely stored in an int, we use an int to store it. However, if it is a floating point number, we use double to store it.