jasder
/
simdjson
1
0
Fork 0
Code Issues Pull Requests Releases 2 Wiki Activity
simdjson/doc/basics.md

8.9 KiB
Raw Blame History

The Basics

An overview of what you need to know to use simdjson, with examples.

Including simdjson

To include simdjson, copy simdjson.h and simdjson.cpp into your project. Then include it in your project with:

#include "simdjson.h"
using namespace simdjson; // optional

You can compile with:

c++ myproject.cpp simdjson.cpp --std=c++17

The Basics: Loading and Parsing JSON Documents

The simdjson library offers a simple DOM tree API, which you can access by creating a document::parser and calling the load() method:

document::parser parser;
document &doc = parser.load(filename); // load and parse a file

Or by creating a padded string (for efficiency reasons, simdjson requires a string with SIMDJSON_PADDING bytes at the end) and calling parse():

document::parser parser;
document &doc = parser.parse("[1,2,3]"_padded); // parse a string

Using the Parsed JSON

Once you have a document, you can navigate it with idiomatic C++ iterators, operators and casts.

  • Document Root: To get the top level JSON element, get doc.root(). Many of the methods below will work on the document object itself, as well.
  • Extracting Values: You can cast a JSON element to a native type: double(element) or double x = json_element. This works for double, uint64_t, int64_t, bool, document::object and document::array. You can also use is_typename()` to test if it is a given type, and as_typename() to do the cast and return an error code on failure instead of an exception.
  • Field Access: To get the value of the "foo" field in an object, use object["foo"].
  • Array Iteration: To iterate through an array, use for (auto value : array) { ... }. If you know the type of the value, you can cast it right there, too! for (double value : array) { ... }
  • Object Iteration: You can iterate through an object's fields, too: for (auto [key, value] : object)

Here are some examples of all of the above:

auto cars_json = R"( [
  { "make": "Toyota", "model": "Camry",  "year": 2018, "tire_pressure": [ 40.1, 39.9, 37.7, 40.4 ] },
  { "make": "Kia",    "model": "Soul",   "year": 2012, "tire_pressure": [ 30.1, 31.0, 28.6, 28.7 ] },
  { "make": "Toyota", "model": "Tercel", "year": 1999, "tire_pressure": [ 29.8, 30.0, 30.2, 30.5 ] }
] )"_padded;
document::parser parser;
document::array cars = parser.parse(cars_json).as_array();

// Iterating through an array of objects
for (document::object car : cars) {
  // Accessing a field by name
  cout << "Make/Model: " << car["make"] << "/" << 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;

  // Writing out all the information about the car
  for (auto [key, value] : car) {
    cout << "- " << key << ": " << value << endl;
  }
}

JSON Pointer

The simdjson library also supports JSON pointer, letting you reach further down into the document:

auto cars_json = R"( [
  { "make": "Toyota", "model": "Camry",  "year": 2018, "tire_pressure": [ 40.1, 39.9, 37.7, 40.4 ] },
  { "make": "Kia",    "model": "Soul",   "year": 2012, "tire_pressure": [ 30.1, 31.0, 28.6, 28.7 ] },
  { "make": "Toyota", "model": "Tercel", "year": 1999, "tire_pressure": [ 29.8, 30.0, 30.2, 30.5 ] }
] )"_padded;
document::parser parser;
document &cars = parser.parse(cars_json);
cout << cars["/0/tire_pressure/1"] << endl; // Prints 39.9

Error Handling

All simdjson APIs that can fail return simdjson_result<T>, which is a <value, error_code> pair. The error codes and values can be accessed directly, reading the error like so:

auto [doc, error] = parser.parse(json); // doc is a document&
if (error) { cerr << error << endl; exit(1); }
// Use document here now that we've checked for the error

When you use the code this way, it is your responsibility to check for error before using the result: if there is an error, the result value will not be valid and using it will caused undefined behavior.

Note: because of the way auto [x, y] works in C++, you have to define new variables each time you use it. If your project treats aliased, this means you can't use the same names in auto [x, error] without triggering warnings or error (and particularly can't use the word "error" every time). To circumvent this, you can use this instead:

document &doc;
error_code error;
parser.parse(json).tie(doc, error); // <-- Assigns to doc and error just like "auto [doc, error]"

Error Handling Example

This is how the example in "Using the Parsed JSON" could be written using only error code checking:

auto cars_json = R"( [
  { "make": "Toyota", "model": "Camry",  "year": 2018, "tire_pressure": [ 40.1, 39.9, 37.7, 40.4 ] },
  { "make": "Kia",    "model": "Soul",   "year": 2012, "tire_pressure": [ 30.1, 31.0, 28.6, 28.7 ] },
  { "make": "Toyota", "model": "Tercel", "year": 1999, "tire_pressure": [ 29.8, 30.0, 30.2, 30.5 ] }
] )"_padded;
document::parser parser;
auto [doc, error] = parser.parse(cars_json);
if (error) { cerr << error << endl; exit(1); }

// Iterating through an array of objects
for (document::element car_element : cars) {
  document::object car;
  car_element.as_object().tie(car, error);
  if (error) { cerr << error << endl; exit(1); }

  // Accessing a field by name
  document::element make, model;
  car["make"].tie(make, error);
  if (error) { cerr << error << endl; exit(1); }
  car["model"].tie(model, error);
  if (error) { cerr << error << endl; exit(1); }
  cout << "Make/Model: " << make << "/" << model << endl;

  // Casting a JSON element to an integer
  uint64_t year;
  car["year"].as_uint64_t().tie(year, error);
  if (error) { cerr << error << endl; exit(1); }
  cout << "- This car is " << 2020 - year << "years old." << endl;

  // Iterating through an array of floats
  double total_tire_pressure = 0;
  for (document::element tire_pressure_element : car["tire_pressure"]) {
    double tire_pressure;
    tire_pressure_element.as_uint64_t().tie(tire_pressure, error);
    if (error) { cerr << error << endl; exit(1); }
    total_tire_pressure += tire_pressure;
  }
  cout << "- Average tire pressure: " << (total_tire_pressure / 4) << endl;

  // Writing out all the information about the car
  for (auto [key, value] : car) {
    cout << "- " << key << ": " << value << endl;
  }
}

Exceptions

Users more comfortable with an exception flow may choose to directly cast the simdjson_result<T> to the desired type:

document &doc = parser.parse(json); // Throws an exception if there was an error!

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.

Newline-Delimited JSON (ndjson) and JSON lines

The simdjson library also support multithreaded JSON streaming through a large file containing many smaller JSON documents in either ndjson or JSON lines format. If your JSON documents all contain arrays or objects, we even support direct file concatenation without whitespace. The concatenated file has no size restrictions (including larger than 4GB), though each individual document must be less than 4GB.

Here is a simple example:

auto ndjson = R"(
{ "foo": 1 }
{ "foo": 2 }
{ "foo": 3 }
)"_padded;
document::parser parser;
for (document &doc : parser.load_many(filename)) {
  cout << doc["foo"] << endl;
}
// Prints 1 2 3

In-memory ndjson strings can be parsed as well, with parser.parse_many(string).

Thread Safety

The simdjson library is mostly single-threaded. Thread safety is the responsibility of the caller: it is unsafe to reuse a document::parser object between different threads.

simdjson's CPU detection, which runs the first time parsing is attempted and switches to the fastest parser for your CPU, is transparent and thread-safe.

The json stream parser is threaded, using a second thread under its own control. Like the single document parser