From c40e85920fa3bee885245387f3a634edcd915740 Mon Sep 17 00:00:00 2001 From: Niels Date: Sun, 21 Jun 2015 09:44:12 +0200 Subject: [PATCH] more documentation --- .gitignore | 1 + Doxyfile | 2 +- Makefile | 11 +- docs/doxyindex.cpp | 16 +- docs/examples/array.cpp | 18 ++ docs/examples/array.output | 4 + docs/examples/basic_json__list_init_t.cpp | 20 ++ docs/examples/basic_json__list_init_t.output | 5 + .../basic_json__size_type_basic_json.cpp | 17 ++ .../basic_json__size_type_basic_json.output | 3 + docs/examples/clear.cpp | 33 +++ docs/examples/clear.output | 7 + docs/examples/max_size.cpp | 24 ++ docs/examples/max_size.output | 7 + docs/examples/object.cpp | 17 ++ docs/examples/object.output | 3 + docs/mylayout.css | 7 + docs/mylayout_docset.css | 15 ++ src/json.hpp | 217 ++++++++++++++++-- src/json.hpp.re2c | 217 ++++++++++++++++-- 20 files changed, 602 insertions(+), 42 deletions(-) create mode 100644 docs/examples/array.cpp create mode 100644 docs/examples/array.output create mode 100644 docs/examples/basic_json__list_init_t.cpp create mode 100644 docs/examples/basic_json__list_init_t.output create mode 100644 docs/examples/basic_json__size_type_basic_json.cpp create mode 100644 docs/examples/basic_json__size_type_basic_json.output create mode 100644 docs/examples/clear.cpp create mode 100644 docs/examples/clear.output create mode 100644 docs/examples/max_size.cpp create mode 100644 docs/examples/max_size.output create mode 100644 docs/examples/object.cpp create mode 100644 docs/examples/object.output create mode 100644 docs/mylayout.css create mode 100644 docs/mylayout_docset.css diff --git a/.gitignore b/.gitignore index 599a43327..4210a192e 100644 --- a/.gitignore +++ b/.gitignore @@ -4,3 +4,4 @@ json_benchmarks working html +me.nlohmann.json.docset diff --git a/Doxyfile b/Doxyfile index cbf2bb99b..057b1df67 100644 --- a/Doxyfile +++ b/Doxyfile @@ -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 diff --git a/Makefile b/Makefile index c927a5118..5f446639f 100644 --- a/Makefile +++ b/Makefile @@ -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@< ObjectType, ArrayType, StringType, BooleanType, NumberIntegerType, NumberFloatType, AllocatorType >@@g' html/*.html + gsed -i 's@< ObjectType, ArrayType, StringType, BooleanType, NumberIntegerType, NumberFloatType, AllocatorType >@@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@< ObjectType, ArrayType, StringType, BooleanType, NumberIntegerType, NumberFloatType, AllocatorType >@@g' html/*.html + gsed -i 's@< ObjectType, ArrayType, StringType, BooleanType, NumberIntegerType, NumberFloatType, AllocatorType >@@g' html/*.html make -C html mv html/*.docset . gsed -i 's@doxygen@json@' me.nlohmann.json.docset/Contents/Info.plist diff --git a/docs/doxyindex.cpp b/docs/doxyindex.cpp index 74ba79fa2..17fe66ed0 100644 --- a/docs/doxyindex.cpp +++ b/docs/doxyindex.cpp @@ -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 -*/ \ No newline at end of file diff --git a/docs/examples/array.cpp b/docs/examples/array.cpp new file mode 100644 index 000000000..106c47a16 --- /dev/null +++ b/docs/examples/array.cpp @@ -0,0 +1,18 @@ +#include + +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'; +} diff --git a/docs/examples/array.output b/docs/examples/array.output new file mode 100644 index 000000000..4e75a1b67 --- /dev/null +++ b/docs/examples/array.output @@ -0,0 +1,4 @@ +[] +[] +[1,2,3,4] +[["one",1],["two",2]] diff --git a/docs/examples/basic_json__list_init_t.cpp b/docs/examples/basic_json__list_init_t.cpp new file mode 100644 index 000000000..393c17ffd --- /dev/null +++ b/docs/examples/basic_json__list_init_t.cpp @@ -0,0 +1,20 @@ +#include + +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'; +} diff --git a/docs/examples/basic_json__list_init_t.output b/docs/examples/basic_json__list_init_t.output new file mode 100644 index 000000000..d38f5b842 --- /dev/null +++ b/docs/examples/basic_json__list_init_t.output @@ -0,0 +1,5 @@ +{} +{"one":1,"two":2} +[1,2,3,4] +{"one":[1],"two":[1,2]} +[[[1],"one"],[[1,2],"two"]] diff --git a/docs/examples/basic_json__size_type_basic_json.cpp b/docs/examples/basic_json__size_type_basic_json.cpp new file mode 100644 index 000000000..1774366d7 --- /dev/null +++ b/docs/examples/basic_json__size_type_basic_json.cpp @@ -0,0 +1,17 @@ +#include + +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'; +} diff --git a/docs/examples/basic_json__size_type_basic_json.output b/docs/examples/basic_json__size_type_basic_json.output new file mode 100644 index 000000000..f4c59b348 --- /dev/null +++ b/docs/examples/basic_json__size_type_basic_json.output @@ -0,0 +1,3 @@ +[] +["Hello"] +["Hello","Hello","Hello","Hello","Hello"] diff --git a/docs/examples/clear.cpp b/docs/examples/clear.cpp new file mode 100644 index 000000000..dcd3cc79b --- /dev/null +++ b/docs/examples/clear.cpp @@ -0,0 +1,33 @@ +#include + +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'; +} diff --git a/docs/examples/clear.output b/docs/examples/clear.output new file mode 100644 index 000000000..0a6269fbf --- /dev/null +++ b/docs/examples/clear.output @@ -0,0 +1,7 @@ +null +false +0 +0 +{} +[] +"" diff --git a/docs/examples/max_size.cpp b/docs/examples/max_size.cpp new file mode 100644 index 000000000..b5537c671 --- /dev/null +++ b/docs/examples/max_size.cpp @@ -0,0 +1,24 @@ +#include + +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'; +} diff --git a/docs/examples/max_size.output b/docs/examples/max_size.output new file mode 100644 index 000000000..8c79995ba --- /dev/null +++ b/docs/examples/max_size.output @@ -0,0 +1,7 @@ +0 +1 +1 +1 +256204778801521550 +1152921504606846975 +1 diff --git a/docs/examples/object.cpp b/docs/examples/object.cpp new file mode 100644 index 000000000..b9198a570 --- /dev/null +++ b/docs/examples/object.cpp @@ -0,0 +1,17 @@ +#include + +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'; +} diff --git a/docs/examples/object.output b/docs/examples/object.output new file mode 100644 index 000000000..f6c27ee8f --- /dev/null +++ b/docs/examples/object.output @@ -0,0 +1,3 @@ +{} +{} +{"one":1,"two":2} diff --git a/docs/mylayout.css b/docs/mylayout.css new file mode 100644 index 000000000..ef310b036 --- /dev/null +++ b/docs/mylayout.css @@ -0,0 +1,7 @@ +.memtemplate { + display: none; +} + +.memTemplParams { + display: none; +} diff --git a/docs/mylayout_docset.css b/docs/mylayout_docset.css new file mode 100644 index 000000000..f18f92073 --- /dev/null +++ b/docs/mylayout_docset.css @@ -0,0 +1,15 @@ +.memtemplate { + display: none; +} + +.memTemplParams { + display: none; +} + +.navtab { + display: none; +} + +#top, .footer { + display: none; +} diff --git a/src/json.hpp b/src/json.hpp index 3e018944a..edc3ec3cb 100644 --- a/src/json.hpp +++ b/src/json.hpp @@ -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 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) diff --git a/src/json.hpp.re2c b/src/json.hpp.re2c index fafef9b2f..2d97b133d 100644 --- a/src/json.hpp.re2c +++ b/src/json.hpp.re2c @@ -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 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)