Adding an example corresponding to issue 1316 (documentation enhancement) (simdjson#1317)

lemire · web-flow · commit 3fa40b8dc207 · 2020-11-27T17:40:29.000-05:00
* Adding an example. * Updated other doc file. * Trying to take into account @jkeiser's comments. * Some people prefer empty final lines.
diff --git 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
@@ -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
@@ -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
@@ -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
@@ -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;
+}
