diff --git a/doc/basics.md b/doc/basics.md index 949498eb6..de8fec6e5 100644 --- a/doc/basics.md +++ b/doc/basics.md @@ -373,14 +373,31 @@ When you use the code this way, it is your responsibility to check for error bef result: if there is an error, the result value will not be valid and using it will caused undefined behavior. -We can write a "quick start" example where we attempt to parse a file and access some data, without triggering exceptions: +We can write a "quick start" example where we attempt to parse the following JSON file and access some data, without triggering exceptions: +```JavaScript +{ + "statuses": [ + { + "id": 505874924095815700 + }, + { + "id": 505874922023837700 + } + ], + "search_metadata": { + "count": 100 + } +} +``` + +Our program loads the file, selects value corresponding to key "search_metadata" which expected to be an object, and then +it selects the key "count" within that object. ```C++ #include "simdjson.h" int main(void) { simdjson::dom::parser parser; - simdjson::dom::element tweets; auto error = parser.load("twitter.json").get(tweets); if (error) { std::cerr << error << std::endl; return EXIT_FAILURE; } @@ -394,6 +411,31 @@ int main(void) { } ``` +The following is a similar example where one wants to get the id of the first tweet without +triggering exceptions. To do this, we use `["statuses"].at(0)["id"]`. We break that expression down: + +- Get the list of tweets (the `"statuses"` key of the document) using `["statuses"]`). The result is expected to be an array. +- Get the first tweet using `.at(0)`. The result is expected to be an object. +- Get the id of the tweet using ["id"]. We expect the value to be a non-negative integer. + +Observe how we use the `at` method when querying an index into an array, and not the bracket operator. + +```C++ +#include "simdjson.h" + +int main(void) { + simdjson::dom::parser parser; + simdjson::dom::element tweets; + auto error = parser.load("twitter.json").get(tweets); + if(error) { std::cerr << error << std::endl; return EXIT_FAILURE; } + uint64_t identifier; + error = tweets["statuses"].at(0)["id"].get(identifier); + if(error) { std::cerr << error << std::endl; return EXIT_FAILURE; } + std::cout << identifier << std::endl; + return EXIT_SUCCESS; +} +``` + ### Error Handling Example This is how the example in "Using the Parsed JSON" could be written using only error code checking: @@ -525,6 +567,21 @@ dom::element doc = parser.parse(json); // Throws an exception if there was an er When used this way, a `simdjson_error` exception will be thrown if an error occurs, preventing the program from continuing if there was an error. + +If one is willing to trigger exceptions, it is possible to write simpler code: + +```C++ +#include "simdjson.h" + +int main(void) { + simdjson::dom::parser parser; + simdjson::dom::element tweets = parser.load("twitter.json"); + std::cout << "ID: " << tweets["statuses"].at(0)["id"] << std::endl; + return EXIT_SUCCESS; +} +``` + + Tree Walking and JSON Element Types ----------------------------------- diff --git a/doc/basics_doxygen.md b/doc/basics_doxygen.md index 595c392a8..466be3448 100644 --- a/doc/basics_doxygen.md +++ b/doc/basics_doxygen.md @@ -354,14 +354,33 @@ When you use the code this way, it is your responsibility to check for error bef result: if there is an error, the result value will not be valid and using it will caused undefined behavior. -We can write a "quick start" example where we attempt to parse a file and access some data, without triggering exceptions: + +We can write a "quick start" example where we attempt to parse the following JSON file and access some data, without triggering exceptions: +```JavaScript +{ + "statuses": [ + { + "id": 505874924095815700 + }, + { + "id": 505874922023837700 + } + ], + "search_metadata": { + "count": 100 + } +} ``` + +Our program loads the file, selects value corresponding to key "search_metadata" which expected to be an object, and then +it selects the key "count" within that object. + +```C++ #include "simdjson.h" int main(void) { simdjson::dom::parser parser; - simdjson::dom::element tweets; auto error = parser.load("twitter.json").get(tweets); if (error) { std::cerr << error << std::endl; return EXIT_FAILURE; } @@ -375,6 +394,32 @@ int main(void) { } ``` + +The following is a similar example where one wants to get the id of the first tweet without +triggering exceptions. To do this, we use `["statuses"].at(0)["id"]`. We break that expression down: + +- Get the list of tweets (the `"statuses"` key of the document) using `["statuses"]`). The result is expected to be an array. +- Get the first tweet using `.at(0)`. The result is expected to be an object. +- Get the id of the tweet using ["id"]. We expect the value to be a non-negative integer. + +Observe how we use the `at` method when querying an index into an array, and not the bracket operator. + +``` +#include "simdjson.h" + +int main(void) { + simdjson::dom::parser parser; + simdjson::dom::element tweets; + auto error = parser.load("twitter.json").get(tweets); + if(error) { std::cerr << error << std::endl; return EXIT_FAILURE; } + uint64_t identifier; + error = tweets["statuses"].at(0)["id"].get(identifier); + if(error) { std::cerr << error << std::endl; return EXIT_FAILURE; } + std::cout << identifier << std::endl; + return EXIT_SUCCESS; +} +``` + ### Error Handling Example This is how the example in "Using the Parsed JSON" could be written using only error code checking: @@ -506,6 +551,21 @@ dom::element doc = parser.parse(json); // Throws an exception if there was an er When used this way, a `simdjson_error` exception will be thrown if an error occurs, preventing the program from continuing if there was an error. + + +If one is willing to trigger exceptions, it is possible to write simpler code: + +``` +#include "simdjson.h" + +int main(void) { + simdjson::dom::parser parser; + simdjson::dom::element tweets = parser.load("twitter.json"); + std::cout << "ID: " << tweets["statuses"].at(0)["id"] << std::endl; + return EXIT_SUCCESS; +} +``` + Tree Walking and JSON Element Types ----------------------------------- diff --git a/examples/quickstart/CMakeLists.txt b/examples/quickstart/CMakeLists.txt index cf4a10048..866d934e9 100644 --- a/examples/quickstart/CMakeLists.txt +++ b/examples/quickstart/CMakeLists.txt @@ -57,4 +57,9 @@ IF(${CMAKE_SYSTEM_NAME} MATCHES "Linux") add_quickstart_test(quickstart_noexceptions quickstart_noexceptions.cpp "" true) add_quickstart_test(quickstart_noexceptions11 quickstart_noexceptions.cpp c++11 true) set_property( TEST quickstart_noexceptions APPEND PROPERTY LABELS acceptance compile ) + + add_quickstart_test(quickstart2_noexceptions quickstart2_noexceptions.cpp "" true) + add_quickstart_test(quickstart2_noexceptions11 quickstart2_noexceptions.cpp c++11 true) + set_property( TEST quickstart2_noexceptions APPEND PROPERTY LABELS acceptance compile ) + endif() diff --git a/examples/quickstart/quickstart2.cpp b/examples/quickstart/quickstart2.cpp new file mode 100644 index 000000000..a276c73f4 --- /dev/null +++ b/examples/quickstart/quickstart2.cpp @@ -0,0 +1,7 @@ +#include "simdjson.h" + +int main(void) { + simdjson::dom::parser parser; + simdjson::dom::element tweets = parser.load("twitter.json"); + std::cout << "ID: " << tweets["statuses"].at(0)["id"] << std::endl; +} diff --git a/examples/quickstart/quickstart2_noexceptions.cpp b/examples/quickstart/quickstart2_noexceptions.cpp new file mode 100644 index 000000000..e13f2b564 --- /dev/null +++ b/examples/quickstart/quickstart2_noexceptions.cpp @@ -0,0 +1,13 @@ +#include "simdjson.h" + +int main(void) { + simdjson::dom::parser parser; + simdjson::dom::element tweets; + auto error = parser.load("twitter.json").get(tweets); + if(error) { std::cerr << error << std::endl; return EXIT_FAILURE; } + uint64_t identifier; + error = tweets["statuses"].at(0)["id"].get(identifier); + if(error) { std::cerr << error << std::endl; return EXIT_FAILURE; } + std::cout << identifier << std::endl; + return EXIT_SUCCESS; +}