diff --git a/doc/basics.md b/doc/basics.md index 0852ffceb..55ac64973 100644 --- a/doc/basics.md +++ b/doc/basics.md @@ -292,6 +292,8 @@ We invite you to keep the following rules in mind: The simdjson library makes generous use of `std::string_view` instances. If you are unfamiliar with `std::string_view` in C++, make sure to [read the section on std::string_view](#string_view). +They behave much like an immutable `std::string` but they require no memory allocation. You can +create a `std::string` instance from an `std::string_view` when you need it. The following specific instructions indicate how to use the JSON when exceptions are enabled, but simdjson has full, idiomatic support for users who avoid exceptions. See [the simdjson error handling documentation](basics.md#error-handling) for more. @@ -628,6 +630,41 @@ for (ondemand::object car : parser.iterate(cars_json)) { } ``` + +The previous example had an array of objects, but we can use essentially the same +approach with an object of objects. + +```c++ +ondemand::parser parser; +auto cars_json = R"( { + "identifier1":{ "make": "Toyota", "model": "Camry", "year": 2018, "tire_pressure": [ 40.1, 39.9, 37.7, 40.4 ] }, + "identifier2":{ "make": "Kia", "model": "Soul", "year": 2012, "tire_pressure": [ 30.1, 31.0, 28.6, 28.7 ] }, + "identifier3":{ "make": "Toyota", "model": "Tercel", "year": 1999, "tire_pressure": [ 29.8, 30.0, 30.2, 30.5 ] } +} )"_padded; +// Iterating through an array of objects +ondemand::document doc = parser.iterate(cars_json); +for (ondemand::field key_car : doc.get_object()) { + // If I need a string_view and/or, I can use key_car.unescaped_key() instead, but + // key_car.key() will be more performant otherwise. + cout << "identifier : " << key_car.key() << std::endl; + // I can now access the subobject: + ondemand::object car = key_car.value(); + // Accessing a field by name + cout << "Make/Model: " << std::string_view(car["make"]) << "/" << std::string_view(car["model"]) << endl; + + // Casting a JSON element to an integer + uint64_t year = car["year"]; + cout << "- This car is " << 2020 - year << "years old." << endl; + + // Iterating through an array of floats + double total_tire_pressure = 0; + for (double tire_pressure : car["tire_pressure"]) { + total_tire_pressure += tire_pressure; + } + cout << "- Average tire pressure: " << (total_tire_pressure / 4) << endl; +} +``` + The following example illustrates how you may also iterate through object values, effectively visiting all key-value pairs in the object. ```C++ diff --git a/tests/ondemand/ondemand_readme_examples.cpp b/tests/ondemand/ondemand_readme_examples.cpp index 931881e8d..af137e919 100644 --- a/tests/ondemand/ondemand_readme_examples.cpp +++ b/tests/ondemand/ondemand_readme_examples.cpp @@ -416,6 +416,40 @@ bool using_the_parsed_json_3() { TEST_SUCCEED(); } +bool using_the_parsed_json_3b() { + TEST_START(); + ondemand::parser parser; + auto cars_json = R"( { + "identifier1":{ "make": "Toyota", "model": "Camry", "year": 2018, "tire_pressure": [ 40.1, 39.9, 37.7, 40.4 ] }, + "identifier2":{ "make": "Kia", "model": "Soul", "year": 2012, "tire_pressure": [ 30.1, 31.0, 28.6, 28.7 ] }, + "identifier3":{ "make": "Toyota", "model": "Tercel", "year": 1999, "tire_pressure": [ 29.8, 30.0, 30.2, 30.5 ] } + } )"_padded; + + // Iterating through an array of objects + ondemand::document doc = parser.iterate(cars_json); + for (ondemand::field key_car : doc.get_object()) { + // If I need a string_view and/or, I can use key_car.unescaped_key() instead, but + // key_car.key() will be more performant otherwise. + cout << "identifier : " << key_car.key() << std::endl; + // I can now access the subobject: + ondemand::object car = key_car.value(); + // Accessing a field by name + cout << "Make/Model: " << std::string_view(car["make"]) << "/" << std::string_view(car["model"]) << endl; + + // Casting a JSON element to an integer + uint64_t year = car["year"]; + cout << "- This car is " << 2020 - year << "years old." << endl; + + // Iterating through an array of floats + double total_tire_pressure = 0; + for (double tire_pressure : car["tire_pressure"]) { + total_tire_pressure += tire_pressure; + } + cout << "- Average tire pressure: " << (total_tire_pressure / 4) << endl; + } + + TEST_SUCCEED(); +} bool using_the_parsed_json_rewind() { TEST_START(); @@ -1187,6 +1221,7 @@ bool run() { && big_integer() && big_integer_in_string() && using_the_parsed_json_3() + && using_the_parsed_json_3b() && using_the_parsed_json_4() && using_the_parsed_json_5() #endif