diff --git a/.gitignore b/.gitignore
index 599a4332..4210a192 100644
--- a/.gitignore
+++ b/.gitignore
@@ -4,3 +4,4 @@ json_benchmarks
working
html
+me.nlohmann.json.docset
diff --git a/Doxyfile b/Doxyfile
index cbf2bb99..057b1df6 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 c927a511..5f446639 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@<string>doxygen</string>@<string>json</string>@' me.nlohmann.json.docset/Contents/Info.plist
diff --git a/docs/doxyindex.cpp b/docs/doxyindex.cpp
index 74ba79fa..17fe66ed 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 00000000..106c47a1
--- /dev/null
+++ b/docs/examples/array.cpp
@@ -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';
+}
diff --git a/docs/examples/array.output b/docs/examples/array.output
new file mode 100644
index 00000000..4e75a1b6
--- /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 00000000..393c17ff
--- /dev/null
+++ b/docs/examples/basic_json__list_init_t.cpp
@@ -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';
+}
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 00000000..d38f5b84
--- /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 00000000..1774366d
--- /dev/null
+++ b/docs/examples/basic_json__size_type_basic_json.cpp
@@ -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';
+}
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 00000000..f4c59b34
--- /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 00000000..dcd3cc79
--- /dev/null
+++ b/docs/examples/clear.cpp
@@ -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';
+}
diff --git a/docs/examples/clear.output b/docs/examples/clear.output
new file mode 100644
index 00000000..0a6269fb
--- /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 00000000..b5537c67
--- /dev/null
+++ b/docs/examples/max_size.cpp
@@ -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';
+}
diff --git a/docs/examples/max_size.output b/docs/examples/max_size.output
new file mode 100644
index 00000000..8c79995b
--- /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 00000000..b9198a57
--- /dev/null
+++ b/docs/examples/object.cpp
@@ -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';
+}
diff --git a/docs/examples/object.output b/docs/examples/object.output
new file mode 100644
index 00000000..f6c27ee8
--- /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 00000000..ef310b03
--- /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 00000000..f18f9207
--- /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 3e018944..edc3ec3c 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<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)
diff --git a/src/json.hpp.re2c b/src/json.hpp.re2c
index fafef9b2..2d97b133 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<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)