j3d1/json
1
0
Fork 0
Code Issues Pull requests Releases Wiki Activity

more documentation

Browse source
This commit is contained in:
Niels 2015-06-21 09:44:12 +02:00
parent bb13c931b3
commit c40e85920f
20 changed files with 602 additions and 42 deletions
Download patch file Download diff file Expand all files Collapse all files

1
.gitignore vendored
View file

@ -4,3 +4,4 @@ json_benchmarks
working
html
me.nlohmann.json.docset

2
Doxyfile
View file

@ -145,7 +145,7 @@ HTML_FILE_EXTENSION = .html
HTML_HEADER =
HTML_FOOTER =
HTML_STYLESHEET =
HTML_EXTRA_STYLESHEET =
HTML_EXTRA_STYLESHEET = docs/mylayout.css
HTML_EXTRA_FILES =
HTML_COLORSTYLE_HUE = 220
HTML_COLORSTYLE_SAT = 100

11
Makefile
View file

@ -15,19 +15,28 @@ clean:
json_unit: test/unit.cpp src/json.hpp test/catch.hpp
$(CXX) -std=c++11 $(CXXFLAGS) $(FLAGS) $(CPPFLAGS) -I src -I test $< $(LDFLAGS) -o $@
# execute the unit tests and check documentation
check: json_unit
./json_unit "*"
make check -C docs/examples
docset:
doxygen: update_docs src/json.hpp
doxygen
gsed -i 's@&lt; ObjectType, ArrayType, StringType, BooleanType, NumberIntegerType, NumberFloatType, AllocatorType &gt;@@g' html/*.html
gsed -i 's@&lt;&#160;ObjectType,&#160;ArrayType,&#160;StringType,&#160;BooleanType,&#160;NumberIntegerType,&#160;NumberFloatType,&#160;AllocatorType&#160;&gt;@@g' html/*.html
docset: update_docs src/json.hpp
cp Doxyfile Doxyfile_docset
gsed -i 's/DISABLE_INDEX = NO/DISABLE_INDEX = YES/' Doxyfile_docset
gsed -i 's/SEARCHENGINE = YES/SEARCHENGINE = NO/' Doxyfile_docset
gsed -i 's/GENERATE_TREEVIEW = YES/GENERATE_TREEVIEW = NO/' Doxyfile_docset
gsed -i 's/SEPARATE_MEMBER_PAGES = NO/SEPARATE_MEMBER_PAGES = YES/' Doxyfile_docset
gsed -i 's/BINARY_TOC = YES/BINARY_TOC = NO/' Doxyfile_docset
gsed -i 's@HTML_EXTRA_STYLESHEET = docs/mylayout.css@HTML_EXTRA_STYLESHEET = docs/mylayout_docset.css@' Doxyfile_docset
rm -fr html *.docset
doxygen Doxyfile_docset
gsed -i 's@&lt; ObjectType, ArrayType, StringType, BooleanType, NumberIntegerType, NumberFloatType, AllocatorType &gt;@@g' html/*.html
gsed -i 's@&lt;&#160;ObjectType,&#160;ArrayType,&#160;StringType,&#160;BooleanType,&#160;NumberIntegerType,&#160;NumberFloatType,&#160;AllocatorType&#160;&gt;@@g' html/*.html
make -C html
mv html/*.docset .
gsed -i 's@<string>doxygen</string>@<string>json</string>@' me.nlohmann.json.docset/Contents/Info.plist

16
docs/doxyindex.cpp
View file

@ -1,21 +1,9 @@
/*!
@mainpage
See @ref nlohmann::basic_json
@copyright Niels Lohmann\n
@include "../../LICENSE.MIT"
*/
/*!
@defgroup container Container
@brief methods and types to satisfy the Container requirements
A Container is an object used to store other objects and taking care of the
management of the memory used by the objects it contains.
@see http://en.cppreference.com/w/cpp/concept/Container
*/
/*!
@defgroup reversiblecontainer Reversible Container
*/

18
docs/examples/array.cpp Normal file
View file

@ -0,0 +1,18 @@
#include <json.hpp>
using namespace nlohmann;
int main()
{
// create JSON arrays
json j_no_init_list = json::array();
json j_empty_init_list = json::array({});
json j_nonempty_init_list = json::array({1, 2, 3, 4});
json j_list_of_pairs = json::array({ {"one", 1}, {"two", 2} });
// serialize the JSON arrays
std::cout << j_no_init_list << '\n';
std::cout << j_empty_init_list << '\n';
std::cout << j_nonempty_init_list << '\n';
std::cout << j_list_of_pairs << '\n';
}

4
docs/examples/array.output Normal file
View file

@ -0,0 +1,4 @@
[]
[]
[1,2,3,4]
[["one",1],["two",2]]

20
docs/examples/basic_json__list_init_t.cpp Normal file
View file

@ -0,0 +1,20 @@
#include <json.hpp>
using namespace nlohmann;
int main()
{
// create JSON values
json j_empty_init_list = json({});
json j_object = { {"one", 1}, {"two", 2} };
json j_array = {1, 2, 3, 4};
json j_nested_object = { {"one", {1}}, {"two", {1, 2}} };
json j_nested_array = { {{1}, "one"}, {{1, 2}, "two"} };
// serialize the JSON value
std::cout << j_empty_init_list << '\n';
std::cout << j_object << '\n';
std::cout << j_array << '\n';
std::cout << j_nested_object << '\n';
std::cout << j_nested_array << '\n';
}

5
docs/examples/basic_json__list_init_t.output Normal file
View file

@ -0,0 +1,5 @@
{}
{"one":1,"two":2}
[1,2,3,4]
{"one":[1],"two":[1,2]}
[[[1],"one"],[[1,2],"two"]]

17
docs/examples/basic_json__size_type_basic_json.cpp Normal file
View file

@ -0,0 +1,17 @@
#include <json.hpp>
using namespace nlohmann;
int main()
{
// create an array by creating copies of a JSON value
json value = "Hello";
json array_0 = json(0, value);
json array_1 = json(1, value);
json array_5 = json(5, value);
// serialize the JSON arrays
std::cout << array_0 << '\n';
std::cout << array_1 << '\n';
std::cout << array_5 << '\n';
}

3
docs/examples/basic_json__size_type_basic_json.output Normal file
View file

@ -0,0 +1,3 @@
[]
["Hello"]
["Hello","Hello","Hello","Hello","Hello"]

33
docs/examples/clear.cpp Normal file
View file

@ -0,0 +1,33 @@
#include <json.hpp>
using namespace nlohmann;
int main()
{
// create JSON values
json j_null;
json j_boolean = true;
json j_number_integer = 17;
json j_number_float = 23.42;
json j_object = {{"one", 1}, {"two", 2}};
json j_array = {1, 2, 4, 8, 16};
json j_string = "Hello, world";
// call clear()
j_null.clear();
j_boolean.clear();
j_number_integer.clear();
j_number_float.clear();
j_object.clear();
j_array.clear();
j_string.clear();
// serialize the cleared values()
std::cout << j_null << '\n';
std::cout << j_boolean << '\n';
std::cout << j_number_integer << '\n';
std::cout << j_number_float << '\n';
std::cout << j_object << '\n';
std::cout << j_array << '\n';
std::cout << j_string << '\n';
}

7
docs/examples/clear.output Normal file
View file

@ -0,0 +1,7 @@
null
false
0
0
{}
[]
""

24
docs/examples/max_size.cpp Normal file
View file

@ -0,0 +1,24 @@
#include <json.hpp>
using namespace nlohmann;
int main()
{
// create JSON values
json j_null;
json j_boolean = true;
json j_number_integer = 17;
json j_number_float = 23.42;
json j_object = {{"one", 1}, {"two", 2}};
json j_array = {1, 2, 4, 8, 16};
json j_string = "Hello, world";
// call max_size()
std::cout << j_null.max_size() << '\n';
std::cout << j_boolean.max_size() << '\n';
std::cout << j_number_integer.max_size() << '\n';
std::cout << j_number_float.max_size() << '\n';
std::cout << j_object.max_size() << '\n';
std::cout << j_array.max_size() << '\n';
std::cout << j_string.max_size() << '\n';
}

7
docs/examples/max_size.output Normal file
View file

@ -0,0 +1,7 @@
0
1
1
1
256204778801521550
1152921504606846975
1

17
docs/examples/object.cpp Normal file
View file

@ -0,0 +1,17 @@
#include <json.hpp>
using namespace nlohmann;
int main()
{
// create JSON arrays
json j_no_init_list = json::object();
json j_empty_init_list = json::object({});
json j_list_of_pairs = json::object({ {"one", 1}, {"two", 2} });
//json j_invalid_list = json::object({ "one", 1 }); // would throw
// serialize the JSON arrays
std::cout << j_no_init_list << '\n';
std::cout << j_empty_init_list << '\n';
std::cout << j_list_of_pairs << '\n';
}

3
docs/examples/object.output Normal file
View file

@ -0,0 +1,3 @@
{}
{}
{"one":1,"two":2}

7
docs/mylayout.css Normal file
View file

@ -0,0 +1,7 @@
.memtemplate {
display: none;
}
.memTemplParams {
display: none;
}

15
docs/mylayout_docset.css Normal file
View file

@ -0,0 +1,15 @@
.memtemplate {
display: none;
}
.memTemplParams {
display: none;
}
.navtab {
display: none;
}
#top, .footer {
display: none;
}

217
src/json.hpp
View file

@ -368,12 +368,12 @@ class basic_json
Value type | initial value
----------- | -------------
null | @c null
boolean | @c false
string | @c ""
number | @c 0
object | @c {}
array | @c []
null | `null`
boolean | `false`
string | `""`
number | `0`
object | `{}`
array | `[]`
@param value the type of the value to create
@ -643,7 +643,72 @@ class basic_json
: basic_json(number_float_t(value))
{}
/// create a container (array or object) from an initializer list
/*!
@brief create a container (array or object) from an initializer list
Creates a JSON value of type array or object from the passed initializer
list @a init. In case @a type_deduction is `true` (default), the type of
the JSON value to be created is deducted from the initializer list @a init
according to the following rules:
1. If the list is empty, an empty JSON object value `{}` is created.
2. If the list consists of pairs whose first element is a string, a JSON
object value is created where the first elements of the pairs are treated
as keys and the second elements are as values.
3. In all other cases, an array is created.
The rules aim to create the best fit between a C++ initializer list and
JSON values. The ratioinale is as follows:
1. The empty initializer list is written as `{}` which is exactly an empty
JSON object.
2. C++ has now way of describing mapped types other than to list a list of
pairs. As JSON requires that keys must be of type string, rule 2 is the
weakest constraint one can pose on initializer lists to interpret them as
an object.
3. In all other cases, the initializer list could not be interpreted as
JSON object type, so interpreting it as JSON array type is safe.
With the rules described above, the following JSON values cannot be expressed by an initializer list:
- the empty array (`[]`): use @ref array(list_init_t) with an empty
initializer list in this case
- arrays whose elements satisfy rule 2: use @ref array(list_init_t) with
the same initializer list in this case
@note When used without parentheses around an empty initializer list, @ref
basic_json() is called instead of this function, yielding the JSON null
value.
@param init initializer list with JSON values
@param type_deduction internal parameter; when set to `true`, the type of
the JSON value is deducted from the initializer list @a init; when set to
`false`, the type provided via @a manual_type is forced. This mode is used
by the functions @ref array(list_init_t) and @ref object(list_init_t).
@param manual_type internal parameter; when @a type_deduction is set to
`false`, the created JSON value will use the provided type (only @ref
value_t::array and @ref value_t::object are valid); when @a type_deduction
is set to `true`, this parameter has no effect
@return a JSON value created from the initializer list @a init; the type is
either an array or an object
@throw std::domain_error if @a type_deduction is `false`, @a manual_type is
`value_t::object`, but @a init contains an element which is not a pair
whose first element is a string
@complexity Linear in the size of the initializer list @a init.
@liveexample{The example below shows how JSON values are created from
initializer lists,basic_json__list_init_t}
@sa @ref basic_json array(list_init_t) - create a JSON array value from
an initializer list
@sa @ref basic_json object(list_init_t) - create a JSON object value from
an initializer list
*/
basic_json(list_init_t init, bool type_deduction = true,
value_t manual_type = value_t::array)
{
@ -701,25 +766,101 @@ class basic_json
}
}
/// explicitly create an array from an initializer list
/*!
@brief explicitly create an array from an initializer list
Creates a JSON array value from a given initializer list. That is, given a
list of values `a, b, c`, creates the JSON value `[a, b, c]`. If the
initializer list is empty, the empty array `[]` is created.
@note This function is only needed to express two edge cases that cannot be
realized with the initializer list constructor (@ref
basic_json(list_init_t, bool, value_t)). These cases are:
1. creating an array whose elements are all pairs whose first element is a
string - in this case, the initializer list constructor would create an
object, taking the first elements as keys
2. creating an empty array - passing the empty initializer list to the
initializer list constructor yields an empty object
@param init initializer list with JSON values to create an array from
(optional)
@return JSON array value
@complexity Linear in the size of @a init.
@liveexample{The following code shows an example for the @ref array
function.,array}
@sa @ref basic_json(list_init_t, bool, value_t) - create a JSON value from
an initializer list
@sa @ref basic_json object(list_init_t) - create a JSON object value from
an initializer list
*/
static basic_json array(list_init_t init = list_init_t())
{
return basic_json(init, false, value_t::array);
}
/// explicitly create an object from an initializer list
/*!
@brief explicitly create an object from an initializer list
Creates a JSON object value from a given initializer list. The initializer
lists elements must be pairs, and their first elments must be strings. If
the initializer list is empty, the empty object `{}` is created.
@note This function is only added for symmetry reasons. In contrast to the
related function @ref basic_json array(list_init_t), there are no cases
which can only be expressed by this function. That is, any initializer list
@a init can also be passed to the initializer list constructor @ref
basic_json(list_init_t, bool, value_t).
@param init initializer list to create an object from (optional)
@return JSON object value
@throw std::domain_error if @a init is not a pair whose first elements are
strings; thrown by @ref basic_json(list_init_t, bool, value_t)
@complexity Linear in the size of @a init.
@liveexample{The following code shows an example for the @ref object
function.,object}
@sa @ref basic_json(list_init_t, bool, value_t) - create a JSON value from
an initializer list
@sa @ref basic_json array(list_init_t) - create a JSON array value from an
initializer list
*/
static basic_json object(list_init_t init = list_init_t())
{
return basic_json(init, false, value_t::object);
}
/// construct an array with count copies of given value
basic_json(size_type count, const basic_json& other)
/*!
@brief construct an array with count copies of given value
Constructs a JSON array value by creating @a count copies of a passed
value. In case @a count is `0`, an empty array is created. As postcondition,
`std::distance(begin(),end()) == count` holds.
@param count the number of JSON copies of @a value to create
@param value the JSON value to copy
@return A JSON array value with @a count copies of @a value.
@complexity Linear in @a count.
@liveexample{The following code shows examples for the @ref
basic_json(size_type\, const basic_json&)
constructor.,basic_json__size_type_basic_json}
*/
basic_json(size_type count, const basic_json& value)
: m_type(value_t::array)
{
AllocatorType<array_t> alloc;
m_value.array = alloc.allocate(1);
alloc.construct(m_value.array, count, other);
alloc.construct(m_value.array, count, value);
}
/// construct a JSON container given an iterator range
@ -2163,6 +2304,34 @@ class basic_json
/*!
@brief returns the maximum possible number of elements
Returns the maximum number of elements a JSON value is able to hold due to
system or library implementation limitations, i.e. `std::distance(begin(),
end())` for the JSON value.
@return The return value depends on the different value types and is
defined as follows:
Value type | return value
----------- | -------------
null | @c 0
boolean | @c 1
string | @c 1
number | @c 1
object | result of function object_t::max_size()
array | result of function array_t::max_size()
@complexity Constant, as long as @ref array_t and @ref object_t satisfy the
Container concept; that is, their max_size() functions have
constant complexity.
@requirement This function satisfies the Container requirements:
- The complexity is constant.
- Has the semantics of returning `b.size()` where `b` is the largest
possible JSON value.
@liveexample{The following code calls @ref max_size on the different value
types. Note the output is implementation specific.,max_size}
@ingroup container
*/
size_type max_size() const noexcept
@ -2202,7 +2371,29 @@ class basic_json
/// @name modifiers
/// @{
/// clears the contents
/*!
@brief clears the contents
Clears the content of a JSON value and resets it to the default value as
if @ref basic_json(value_t) would have been called:
Value type | initial value
----------- | -------------
null | `null`
boolean | `false`
string | `""`
number | `0`
object | `{}`
array | `[]`
@note Floating-point numbers are set to `0.0` which will be serialized to
`0`. The vale type remains @ref number_float_t.
@complexity Linear in the size of the JSON value.
@liveexample{The example below shows the effect of @ref clear to different
JSON value types.,clear}
*/
void clear() noexcept
{
switch (m_type)

217
src/json.hpp.re2c
View file

@ -368,12 +368,12 @@ class basic_json
Value type | initial value
----------- | -------------
null | @c null
boolean | @c false
string | @c ""
number | @c 0
object | @c {}
array | @c []
null | `null`
boolean | `false`
string | `""`
number | `0`
object | `{}`
array | `[]`
@param value the type of the value to create
@ -643,7 +643,72 @@ class basic_json
: basic_json(number_float_t(value))
{}
/// create a container (array or object) from an initializer list
/*!
@brief create a container (array or object) from an initializer list
Creates a JSON value of type array or object from the passed initializer
list @a init. In case @a type_deduction is `true` (default), the type of
the JSON value to be created is deducted from the initializer list @a init
according to the following rules:
1. If the list is empty, an empty JSON object value `{}` is created.
2. If the list consists of pairs whose first element is a string, a JSON
object value is created where the first elements of the pairs are treated
as keys and the second elements are as values.
3. In all other cases, an array is created.
The rules aim to create the best fit between a C++ initializer list and
JSON values. The ratioinale is as follows:
1. The empty initializer list is written as `{}` which is exactly an empty
JSON object.
2. C++ has now way of describing mapped types other than to list a list of
pairs. As JSON requires that keys must be of type string, rule 2 is the
weakest constraint one can pose on initializer lists to interpret them as
an object.
3. In all other cases, the initializer list could not be interpreted as
JSON object type, so interpreting it as JSON array type is safe.
With the rules described above, the following JSON values cannot be expressed by an initializer list:
- the empty array (`[]`): use @ref array(list_init_t) with an empty
initializer list in this case
- arrays whose elements satisfy rule 2: use @ref array(list_init_t) with
the same initializer list in this case
@note When used without parentheses around an empty initializer list, @ref
basic_json() is called instead of this function, yielding the JSON null
value.
@param init initializer list with JSON values
@param type_deduction internal parameter; when set to `true`, the type of
the JSON value is deducted from the initializer list @a init; when set to
`false`, the type provided via @a manual_type is forced. This mode is used
by the functions @ref array(list_init_t) and @ref object(list_init_t).
@param manual_type internal parameter; when @a type_deduction is set to
`false`, the created JSON value will use the provided type (only @ref
value_t::array and @ref value_t::object are valid); when @a type_deduction
is set to `true`, this parameter has no effect
@return a JSON value created from the initializer list @a init; the type is
either an array or an object
@throw std::domain_error if @a type_deduction is `false`, @a manual_type is
`value_t::object`, but @a init contains an element which is not a pair
whose first element is a string
@complexity Linear in the size of the initializer list @a init.
@liveexample{The example below shows how JSON values are created from
initializer lists,basic_json__list_init_t}
@sa @ref basic_json array(list_init_t) - create a JSON array value from
an initializer list
@sa @ref basic_json object(list_init_t) - create a JSON object value from
an initializer list
*/
basic_json(list_init_t init, bool type_deduction = true,
value_t manual_type = value_t::array)
{
@ -701,25 +766,101 @@ class basic_json
}
}
/// explicitly create an array from an initializer list
/*!
@brief explicitly create an array from an initializer list
Creates a JSON array value from a given initializer list. That is, given a
list of values `a, b, c`, creates the JSON value `[a, b, c]`. If the
initializer list is empty, the empty array `[]` is created.
@note This function is only needed to express two edge cases that cannot be
realized with the initializer list constructor (@ref
basic_json(list_init_t, bool, value_t)). These cases are:
1. creating an array whose elements are all pairs whose first element is a
string - in this case, the initializer list constructor would create an
object, taking the first elements as keys
2. creating an empty array - passing the empty initializer list to the
initializer list constructor yields an empty object
@param init initializer list with JSON values to create an array from
(optional)
@return JSON array value
@complexity Linear in the size of @a init.
@liveexample{The following code shows an example for the @ref array
function.,array}
@sa @ref basic_json(list_init_t, bool, value_t) - create a JSON value from
an initializer list
@sa @ref basic_json object(list_init_t) - create a JSON object value from
an initializer list
*/
static basic_json array(list_init_t init = list_init_t())
{
return basic_json(init, false, value_t::array);
}
/// explicitly create an object from an initializer list
/*!
@brief explicitly create an object from an initializer list
Creates a JSON object value from a given initializer list. The initializer
lists elements must be pairs, and their first elments must be strings. If
the initializer list is empty, the empty object `{}` is created.
@note This function is only added for symmetry reasons. In contrast to the
related function @ref basic_json array(list_init_t), there are no cases
which can only be expressed by this function. That is, any initializer list
@a init can also be passed to the initializer list constructor @ref
basic_json(list_init_t, bool, value_t).
@param init initializer list to create an object from (optional)
@return JSON object value
@throw std::domain_error if @a init is not a pair whose first elements are
strings; thrown by @ref basic_json(list_init_t, bool, value_t)
@complexity Linear in the size of @a init.
@liveexample{The following code shows an example for the @ref object
function.,object}
@sa @ref basic_json(list_init_t, bool, value_t) - create a JSON value from
an initializer list
@sa @ref basic_json array(list_init_t) - create a JSON array value from an
initializer list
*/
static basic_json object(list_init_t init = list_init_t())
{
return basic_json(init, false, value_t::object);
}
/// construct an array with count copies of given value
basic_json(size_type count, const basic_json& other)
/*!
@brief construct an array with count copies of given value
Constructs a JSON array value by creating @a count copies of a passed
value. In case @a count is `0`, an empty array is created. As postcondition,
`std::distance(begin(),end()) == count` holds.
@param count the number of JSON copies of @a value to create
@param value the JSON value to copy
@return A JSON array value with @a count copies of @a value.
@complexity Linear in @a count.
@liveexample{The following code shows examples for the @ref
basic_json(size_type\, const basic_json&)
constructor.,basic_json__size_type_basic_json}
*/
basic_json(size_type count, const basic_json& value)
: m_type(value_t::array)
{
AllocatorType<array_t> alloc;
m_value.array = alloc.allocate(1);
alloc.construct(m_value.array, count, other);
alloc.construct(m_value.array, count, value);
}
/// construct a JSON container given an iterator range
@ -2163,6 +2304,34 @@ class basic_json
/*!
@brief returns the maximum possible number of elements
Returns the maximum number of elements a JSON value is able to hold due to
system or library implementation limitations, i.e. `std::distance(begin(),
end())` for the JSON value.
@return The return value depends on the different value types and is
defined as follows:
Value type | return value
----------- | -------------
null | @c 0
boolean | @c 1
string | @c 1
number | @c 1
object | result of function object_t::max_size()
array | result of function array_t::max_size()
@complexity Constant, as long as @ref array_t and @ref object_t satisfy the
Container concept; that is, their max_size() functions have
constant complexity.
@requirement This function satisfies the Container requirements:
- The complexity is constant.
- Has the semantics of returning `b.size()` where `b` is the largest
possible JSON value.
@liveexample{The following code calls @ref max_size on the different value
types. Note the output is implementation specific.,max_size}
@ingroup container
*/
size_type max_size() const noexcept
@ -2202,7 +2371,29 @@ class basic_json
/// @name modifiers
/// @{
/// clears the contents
/*!
@brief clears the contents
Clears the content of a JSON value and resets it to the default value as
if @ref basic_json(value_t) would have been called:
Value type | initial value
----------- | -------------
null | `null`
boolean | `false`
string | `""`
number | `0`
object | `{}`
array | `[]`
@note Floating-point numbers are set to `0.0` which will be serialized to
`0`. The vale type remains @ref number_float_t.
@complexity Linear in the size of the JSON value.
@liveexample{The example below shows the effect of @ref clear to different
JSON value types.,clear}
*/
void clear() noexcept
{
switch (m_type)