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

📝 improved documentation

Browse source
This commit is contained in:
Niels Lohmann 2017-08-29 23:46:26 +02:00
parent 5b71bf09a1
commit 91e0032853
No known key found for this signature in database
GPG key ID: 7F3CEA63AE251B69
39 changed files with 532 additions and 101 deletions
Download patch file Download diff file Expand all files Collapse all files

25
doc/Doxyfile
View file

@ -1,4 +1,4 @@
# Doxyfile 1.8.9.1
# Doxyfile 1.8.14
#---------------------------------------------------------------------------
# Project related configuration options
@ -6,7 +6,7 @@
DOXYFILE_ENCODING = UTF-8
PROJECT_NAME = "JSON for Modern C++"
PROJECT_NUMBER = 2.1.1
PROJECT_BRIEF =
PROJECT_BRIEF =
PROJECT_LOGO =
OUTPUT_DIRECTORY = .
CREATE_SUBDIRS = NO
@ -27,10 +27,10 @@ MULTILINE_CPP_IS_BRIEF = NO
INHERIT_DOCS = YES
SEPARATE_MEMBER_PAGES = YES
TAB_SIZE = 4
ALIASES = "complexity=@par Complexity\n"
ALIASES += liveexample{2}="@par Example\n \1 \n @includelineno \2.cpp \n Output (play with this example @htmlinclude \2.link):\n @verbinclude \2.output \n The example code above can be translated with @verbatim g++ -std=c++11 -Isrc doc/examples/\2.cpp -o \2 @endverbatim"
ALIASES += requirement="@par Requirements\n"
ALIASES += exceptionsafety="@par Exception safety\n"
ALIASES = "complexity=@par Complexity\n" \
"liveexample{2}=@par Example\n \1 \n @includelineno \2.cpp \n Output (play with this example @htmlinclude \2.link):\n @verbinclude \2.output \n The <a href= https://github.com/nlohmann/json/blob/develop/doc/examples/\2.cpp>example code</a> above can be translated with @verbatim g++ -std=c++11 -Isrc doc/examples/\2.cpp -o \2 @endverbatim" \
"requirement=@par Requirements\n" \
"exceptionsafety=@par Exception safety\n"
TCL_SUBST =
OPTIMIZE_OUTPUT_FOR_C = NO
OPTIMIZE_OUTPUT_JAVA = NO
@ -38,12 +38,14 @@ OPTIMIZE_FOR_FORTRAN = NO
OPTIMIZE_OUTPUT_VHDL = NO
EXTENSION_MAPPING =
MARKDOWN_SUPPORT = YES
TOC_INCLUDE_HEADINGS = 0
AUTOLINK_SUPPORT = NO
BUILTIN_STL_SUPPORT = YES
CPP_CLI_SUPPORT = NO
SIP_SUPPORT = NO
IDL_PROPERTY_SUPPORT = YES
DISTRIBUTE_GROUP_DOC = NO
GROUP_NESTED_COMPOUNDS = NO
SUBGROUPING = YES
INLINE_GROUPED_CLASSES = NO
INLINE_SIMPLE_STRUCTS = NO
@ -97,12 +99,14 @@ WARNINGS = YES
WARN_IF_UNDOCUMENTED = YES
WARN_IF_DOC_ERROR = YES
WARN_NO_PARAMDOC = YES
WARN_AS_ERROR = NO
WARN_FORMAT = "$file:$line: $text"
WARN_LOGFILE =
#---------------------------------------------------------------------------
# Configuration options related to the input files
#---------------------------------------------------------------------------
INPUT = ../src/json.hpp index.md
INPUT = ../src/json.hpp \
index.md
INPUT_ENCODING = UTF-8
FILE_PATTERNS =
RECURSIVE = NO
@ -131,6 +135,8 @@ REFERENCES_LINK_SOURCE = NO
SOURCE_TOOLTIPS = YES
USE_HTAGS = NO
VERBATIM_HEADERS = NO
CLANG_ASSISTED_PARSING = YES
CLANG_OPTIONS = -std=c++11
#---------------------------------------------------------------------------
# Configuration options related to the alphabetical class index
#---------------------------------------------------------------------------
@ -152,13 +158,14 @@ HTML_COLORSTYLE_HUE = 220
HTML_COLORSTYLE_SAT = 100
HTML_COLORSTYLE_GAMMA = 80
HTML_TIMESTAMP = YES
HTML_DYNAMIC_MENUS = YES
HTML_DYNAMIC_SECTIONS = YES
HTML_INDEX_NUM_ENTRIES = 100
GENERATE_DOCSET = YES
DOCSET_FEEDNAME = "Doxygen generated docs"
DOCSET_BUNDLE_ID = me.nlohmann.json
DOCSET_PUBLISHER_ID = me.nlohmann
DOCSET_PUBLISHER_NAME = Niels Lohmann
DOCSET_PUBLISHER_NAME = NielsLohmann
GENERATE_HTMLHELP = NO
CHM_FILE =
HHC_LOCATION =
@ -215,6 +222,7 @@ LATEX_BATCHMODE = NO
LATEX_HIDE_INDICES = NO
LATEX_SOURCE_CODE = NO
LATEX_BIB_STYLE = plain
LATEX_TIMESTAMP = NO
#---------------------------------------------------------------------------
# Configuration options related to the RTF output
#---------------------------------------------------------------------------
@ -308,6 +316,7 @@ DOTFILE_DIRS =
MSCFILE_DIRS =
DIAFILE_DIRS =
PLANTUML_JAR_PATH =
PLANTUML_CFG_FILE =
PLANTUML_INCLUDE_PATH =
DOT_GRAPH_MAX_NODES = 50
MAX_DOT_GRAPH_DEPTH = 0

6
doc/examples/basic_json__CompatibleType.cpp
View file

@ -5,6 +5,7 @@
#include <set>
#include <unordered_map>
#include <unordered_set>
#include <valarray>
#include "json.hpp"
using json = nlohmann::json;
@ -67,6 +68,10 @@ int main()
std::vector<int> c_vector {1, 2, 3, 4};
json j_vec(c_vector);
// create an array from std::valarray
std::valarray<short> c_valarray {10, 9, 8, 7};
json j_valarray(c_valarray);
// create an array from std::deque
std::deque<double> c_deque {1.2, 2.3, 3.4, 5.6};
json j_deque(c_deque);
@ -102,6 +107,7 @@ int main()
// serialize the JSON arrays
std::cout << j_array_t << '\n';
std::cout << j_vec << '\n';
std::cout << j_valarray << '\n';
std::cout << j_deque << '\n';
std::cout << j_list << '\n';
std::cout << j_flist << '\n';

2
doc/examples/basic_json__CompatibleType.link
View file

@ -1 +1 @@
<a target="_blank" href="https://wandbox.org/permlink/chmc1rH7aNZTIVSp"><b>online</b></a>
<a target="_blank" href="https://wandbox.org/permlink/s7Ecy7hDYSmUWHyx"><b>online</b></a>

1
doc/examples/basic_json__CompatibleType.output
View file

@ -6,6 +6,7 @@
["one","two",3,4.5,false]
[1,2,3,4]
[10,9,8,7]
[1.2,2.3,3.4,5.6]
[true,true,false,true]
[12345678909876,23456789098765,34567890987654,45678909876543]

28
doc/examples/dump.cpp
View file

@ -8,16 +8,24 @@ int main()
// create JSON values
json j_object = {{"one", 1}, {"two", 2}};
json j_array = {1, 2, 4, 8, 16};
json j_string = "Hellö 😀!";
// call dump()
std::cout << j_object.dump() << "\n\n";
std::cout << j_object.dump(-1) << "\n\n";
std::cout << j_object.dump(0) << "\n\n";
std::cout << j_object.dump(4) << "\n\n";
std::cout << j_object.dump(1, '\t') << "\n\n";
std::cout << j_array.dump() << "\n\n";
std::cout << j_array.dump(-1) << "\n\n";
std::cout << j_array.dump(0) << "\n\n";
std::cout << j_array.dump(4) << "\n\n";
std::cout << j_array.dump(1, '\t') << "\n\n";
std::cout << "objects:" << '\n'
<< j_object.dump() << "\n\n"
<< j_object.dump(-1) << "\n\n"
<< j_object.dump(0) << "\n\n"
<< j_object.dump(4) << "\n\n"
<< j_object.dump(1, '\t') << "\n\n";
std::cout << "arrays:" << '\n'
<< j_array.dump() << "\n\n"
<< j_array.dump(-1) << "\n\n"
<< j_array.dump(0) << "\n\n"
<< j_array.dump(4) << "\n\n"
<< j_array.dump(1, '\t') << "\n\n";
std::cout << "strings:" << '\n'
<< j_string.dump() << '\n'
<< j_string.dump(-1, ' ', true) << '\n';
}

2
doc/examples/dump.link
View file

@ -1 +1 @@
<a target="_blank" href="https://wandbox.org/permlink/0rB2LKUCjPlU90XK"><b>online</b></a>
<a target="_blank" href="https://wandbox.org/permlink/UnV6etCOZZRZpYyB"><b>online</b></a>

5
doc/examples/dump.output
View file

@ -1,3 +1,4 @@
objects:
{"one":1,"two":2}
{"one":1,"two":2}
@ -17,6 +18,7 @@
"two": 2
}
arrays:
[1,2,4,8,16]
[1,2,4,8,16]
@ -45,3 +47,6 @@
16
]
strings:
"Hellö 😀!"
"Hell\u00f6 \ud83d\ude00!"

20
doc/examples/exception.cpp Normal file
View file

@ -0,0 +1,20 @@
#include <iostream>
#include "json.hpp"
using json = nlohmann::json;
int main()
{
try
{
// calling at() for a non-existing key
json j = {{"foo", "bar"}};
json k = j.at("non-existing");
}
catch (json::exception& e)
{
// output exception information
std::cout << "message: " << e.what() << '\n'
<< "exception id: " << e.id << std::endl;
}
}

1
doc/examples/exception.link Normal file
View file

@ -0,0 +1 @@
<a target="_blank" href="https://wandbox.org/permlink/yHjdsKGTYSRFNzD7"><b>online</b></a>

2
doc/examples/exception.output Normal file
View file

@ -0,0 +1,2 @@
message: [json.exception.out_of_range.403] key 'non-existing' not found
exception id: 403

21
doc/examples/invalid_iterator.cpp Normal file
View file

@ -0,0 +1,21 @@
#include <iostream>
#include "json.hpp"
using json = nlohmann::json;
int main()
{
try
{
// calling iterator::key() on non-object iterator
json j = "string";
json::iterator it = j.begin();
auto k = it.key();
}
catch (json::invalid_iterator& e)
{
// output exception information
std::cout << "message: " << e.what() << '\n'
<< "exception id: " << e.id << std::endl;
}
}

1
doc/examples/invalid_iterator.link Normal file
View file

@ -0,0 +1 @@
<a target="_blank" href="https://wandbox.org/permlink/PW9dQWFyNaUxzEVY"><b>online</b></a>

2
doc/examples/invalid_iterator.output Normal file
View file

@ -0,0 +1,2 @@
message: [json.exception.invalid_iterator.207] cannot use key() for non-object iterators
exception id: 207

5
doc/examples/operator__value_t.cpp
View file

@ -8,7 +8,8 @@ int main()
// create JSON values
json j_null;
json j_boolean = true;
json j_number_integer = 17;
json j_number_integer = -17;
json j_number_unsigned = 42u;
json j_number_float = 23.42;
json j_object = {{"one", 1}, {"two", 2}};
json j_array = {1, 2, 4, 8, 16};
@ -18,6 +19,7 @@ int main()
json::value_t t_null = j_null;
json::value_t t_boolean = j_boolean;
json::value_t t_number_integer = j_number_integer;
json::value_t t_number_unsigned = j_number_unsigned;
json::value_t t_number_float = j_number_float;
json::value_t t_object = j_object;
json::value_t t_array = j_array;
@ -28,6 +30,7 @@ int main()
std::cout << (t_null == json::value_t::null) << '\n';
std::cout << (t_boolean == json::value_t::boolean) << '\n';
std::cout << (t_number_integer == json::value_t::number_integer) << '\n';
std::cout << (t_number_unsigned == json::value_t::number_unsigned) << '\n';
std::cout << (t_number_float == json::value_t::number_float) << '\n';
std::cout << (t_object == json::value_t::object) << '\n';
std::cout << (t_array == json::value_t::array) << '\n';

2
doc/examples/operator__value_t.link
View file

@ -1 +1 @@
<a target="_blank" href="https://wandbox.org/permlink/daNU6Fj8JuV07nBn"><b>online</b></a>
<a target="_blank" href="https://wandbox.org/permlink/aUlH5rQeIA002APo"><b>online</b></a>

1
doc/examples/operator__value_t.output
View file

@ -5,3 +5,4 @@ true
true
true
true
true

29
doc/examples/other_error.cpp Normal file
View file

@ -0,0 +1,29 @@
#include <iostream>
#include "json.hpp"
using json = nlohmann::json;
int main()
{
try
{
// executing a failing JSON Patch operation
json value = R"({
"best_biscuit": {
"name": "Oreo"
}
})"_json;
json patch = R"([{
"op": "test",
"path": "/best_biscuit/name",
"value": "Choco Leibniz"
}])"_json;
value.patch(patch);
}
catch (json::other_error& e)
{
// output exception information
std::cout << "message: " << e.what() << '\n'
<< "exception id: " << e.id << std::endl;
}
}

1
doc/examples/other_error.link Normal file
View file

@ -0,0 +1 @@
<a target="_blank" href="https://wandbox.org/permlink/UcADWdVMPA9GZbRP"><b>online</b></a>

2
doc/examples/other_error.output Normal file
View file

@ -0,0 +1,2 @@
message: [json.exception.other_error.501] unsuccessful: {"op":"test","path":"/best_biscuit/name","value":"Choco Leibniz"}
exception id: 501

20
doc/examples/out_of_range.cpp Normal file
View file

@ -0,0 +1,20 @@
#include <iostream>
#include "json.hpp"
using json = nlohmann::json;
int main()
{
try
{
// calling at() for an invalid index
json j = {1, 2, 3, 4};
j.at(4) = 10;
}
catch (json::out_of_range& e)
{
// output exception information
std::cout << "message: " << e.what() << '\n'
<< "exception id: " << e.id << std::endl;
}
}

1
doc/examples/out_of_range.link Normal file
View file

@ -0,0 +1 @@
<a target="_blank" href="https://wandbox.org/permlink/VrsKXxX3CuHeqKq7"><b>online</b></a>

2
doc/examples/out_of_range.output Normal file
View file

@ -0,0 +1,2 @@
message: [json.exception.out_of_range.401] array index 4 is out of range
exception id: 401

20
doc/examples/parse_error.cpp Normal file
View file

@ -0,0 +1,20 @@
#include <iostream>
#include "json.hpp"
using json = nlohmann::json;
int main()
{
try
{
// parsing input with a syntax error
json::parse("[1,2,3,]");
}
catch (json::parse_error& e)
{
// output exception information
std::cout << "message: " << e.what() << '\n'
<< "exception id: " << e.id << '\n'
<< "byte position of error: " << e.byte << std::endl;
}
}

1
doc/examples/parse_error.link Normal file
View file

@ -0,0 +1 @@
<a target="_blank" href="https://wandbox.org/permlink/74sQTauZsM8tWyuM"><b>online</b></a>

3
doc/examples/parse_error.output Normal file
View file

@ -0,0 +1,3 @@
message: [json.exception.parse_error.101] parse error at 8: syntax error - unexpected ']'; expected '[', '{', or a literal
exception id: 101
byte position of error: 8

4
doc/examples/type.cpp
View file

@ -8,7 +8,8 @@ int main()
// create JSON values
json j_null;
json j_boolean = true;
json j_number_integer = 17;
json j_number_integer = -17;
json j_number_unsigned = 42u;
json j_number_float = 23.42;
json j_object = {{"one", 1}, {"two", 2}};
json j_array = {1, 2, 4, 8, 16};
@ -19,6 +20,7 @@ int main()
std::cout << (j_null.type() == json::value_t::null) << '\n';
std::cout << (j_boolean.type() == json::value_t::boolean) << '\n';
std::cout << (j_number_integer.type() == json::value_t::number_integer) << '\n';
std::cout << (j_number_unsigned.type() == json::value_t::number_unsigned) << '\n';
std::cout << (j_number_float.type() == json::value_t::number_float) << '\n';
std::cout << (j_object.type() == json::value_t::object) << '\n';
std::cout << (j_array.type() == json::value_t::array) << '\n';

2
doc/examples/type.link
View file

@ -1 +1 @@
<a target="_blank" href="https://wandbox.org/permlink/zlWezYhiRTnLzrSj"><b>online</b></a>
<a target="_blank" href="https://wandbox.org/permlink/LqgeAtdIMLSpGzkE"><b>online</b></a>

1
doc/examples/type.output
View file

@ -5,3 +5,4 @@ true
true
true
true
true

20
doc/examples/type_error.cpp Normal file
View file

@ -0,0 +1,20 @@
#include <iostream>
#include "json.hpp"
using json = nlohmann::json;
int main()
{
try
{
// calling push_back() on a string value
json j = "string";
j.push_back("another string");
}
catch (json::type_error& e)
{
// output exception information
std::cout << "message: " << e.what() << '\n'
<< "exception id: " << e.id << std::endl;
}
}

1
doc/examples/type_error.link Normal file
View file

@ -0,0 +1 @@
<a target="_blank" href="https://wandbox.org/permlink/HVfmgdIq73ztfCHY"><b>online</b></a>

2
doc/examples/type_error.output Normal file
View file

@ -0,0 +1,2 @@
message: [json.exception.type_error.308] cannot use push_back() with string
exception id: 308

18
doc/examples/type_name.cpp
View file

@ -8,18 +8,20 @@ int main()
// create JSON values
json j_null;
json j_boolean = true;
json j_number_integer = 17;
json j_number_integer = -17;
json j_number_unsigned = 42u;
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 type_name()
std::cout << j_null.type_name() << '\n';
std::cout << j_boolean.type_name() << '\n';
std::cout << j_number_integer.type_name() << '\n';
std::cout << j_number_float.type_name() << '\n';
std::cout << j_object.type_name() << '\n';
std::cout << j_array.type_name() << '\n';
std::cout << j_string.type_name() << '\n';
std::cout << j_null << " is a " << j_null.type_name() << '\n';
std::cout << j_boolean << " is a " << j_boolean.type_name() << '\n';
std::cout << j_number_integer << " is a " << j_number_integer.type_name() << '\n';
std::cout << j_number_unsigned << " is a " << j_number_unsigned.type_name() << '\n';
std::cout << j_number_float << " is a " << j_number_float.type_name() << '\n';
std::cout << j_object << " is an " << j_object.type_name() << '\n';
std::cout << j_array << " is an " << j_array.type_name() << '\n';
std::cout << j_string << " is a " << j_string.type_name() << '\n';
}

2
doc/examples/type_name.link
View file

@ -1 +1 @@
<a target="_blank" href="https://wandbox.org/permlink/dKXdftLJYVnkE3Vg"><b>online</b></a>
<a target="_blank" href="https://wandbox.org/permlink/UqDa9aT5fHaK6dPQ"><b>online</b></a>

15
doc/examples/type_name.output
View file

@ -1,7 +1,8 @@
null
boolean
number
number
object
array
string
null is a null
true is a boolean
-17 is a number
42 is a number
23.42 is a number
{"one":1,"two":2} is an object
[1,2,4,8,16] is an array
"Hello, world" is a string