From 5eb748ae17daadb52158f4cafe85af6671e2f3f4 Mon Sep 17 00:00:00 2001 From: Daniel Lemire Date: Tue, 23 Jun 2020 09:33:15 -0400 Subject: [PATCH 1/2] This improves slightly the documentation, adding instructions for CMake users. --- doc/basics.md | 93 +++++++++++++++++++++++++++++++++------------------ 1 file changed, 61 insertions(+), 32 deletions(-) diff --git a/doc/basics.md b/doc/basics.md index 35ea7a1b..83dbdf97 100644 --- a/doc/basics.md +++ b/doc/basics.md @@ -5,8 +5,12 @@ An overview of what you need to know to use simdjson, with examples. * [Requirements](#requirements) * [Including simdjson](#including-simdjson) +* [Using simdjson as a CMake dependency](#using-simdjson-as-a-cmake-dependency) * [The Basics: Loading and Parsing JSON Documents](#the-basics-loading-and-parsing-json-documents) * [Using the Parsed JSON](#using-the-parsed-json) +* [C++17 Support](#c++17-support) +* [Minifying JSON strings without parsing](#minifying-json-strings-without-parsing) +* [UTF-8 validation (alone)](#utf-8-validation-alone) * [JSON Pointer](#json-pointer) * [Error Handling](#error-handling) * [Error Handling Example](#error-handling-example) @@ -44,6 +48,31 @@ Note: - Visual Studio users should compile with the `_CRT_SECURE_NO_WARNINGS` flag to avoid warnings with respect to our use of standard C functions such as `fopen`. + + +Using simdjson as a CMake dependency +------------------ + + + +You can include the simdjson repository as a folder in your CMake project. In the parent +`CMakeLists.txt` include the following lines: + +``` +set(SIMDJSON_JUST_LIBRARY ON CACHE STRING "Build just the library, nothing else." FORCE) +add_subdirectory(simdjson EXCLUDE_FROM_ALL) +``` + +Elsewhere in your project, you can declare dependencies on simdjson with lines such as these: + +``` +add_executable(myprogram myprogram.cpp) + +target_link_libraries(myprogram simdjson) +``` + +See [our CMake demonstration](https://github.com/simdjson/cmakedemo). + The Basics: Loading and Parsing JSON Documents ---------------------------------------------- @@ -168,6 +197,38 @@ And another one: cout << "number: " << v << endl; ``` +C++17 Support +------------- + +While the simdjson library can be used in any project using C++ 11 and above, it has special support +for C++ 17. The APIs for field iteration and error handling in particular are designed to work +nicely with C++17's destructuring syntax. For example: + +```c++ +dom::parser parser; +padded_string json = R"( { "foo": 1, "bar": 2 } )"_padded; +auto [object, error] = parser.parse(json).get(); +if (error) { cerr << error << endl; return; } +for (auto [key, value] : object) { + cout << key << " = " << value << endl; +} +``` + +For comparison, here is the C++ 11 version of the same code: + +```c++ +// C++ 11 version for comparison +dom::parser parser; +padded_string json = R"( { "foo": 1, "bar": 2 } )"_padded; +simdjson::error_code error; +dom::object object; +error = parser.parse(json).get(object); +if (!error) { cerr << error << endl; return; } +for (dom::key_value_pair field : object) { + cout << field.key << " = " << field.value << endl; +} +``` + Minifying JSON strings without parsing ---------------------- @@ -205,38 +266,6 @@ The UTF-8 validation function merely checks that the input is valid UTF-8: it wo Your input string does not need any padding. Any string will do. The `validate_utf8` function does not do any memory allocation on the heap, and it does not throw exceptions. -C++17 Support -------------- - -While the simdjson library can be used in any project using C++ 11 and above, it has special support -for C++ 17. The APIs for field iteration and error handling in particular are designed to work -nicely with C++17's destructuring syntax. For example: - -```c++ -dom::parser parser; -padded_string json = R"( { "foo": 1, "bar": 2 } )"_padded; -auto [object, error] = parser.parse(json).get(); -if (error) { cerr << error << endl; return; } -for (auto [key, value] : object) { - cout << key << " = " << value << endl; -} -``` - -For comparison, here is the C++ 11 version of the same code: - -```c++ -// C++ 11 version for comparison -dom::parser parser; -padded_string json = R"( { "foo": 1, "bar": 2 } )"_padded; -simdjson::error_code error; -dom::object object; -error = parser.parse(json).get(object); -if (!error) { cerr << error << endl; return; } -for (dom::key_value_pair field : object) { - cout << field.key << " = " << field.value << endl; -} -``` - JSON Pointer ------------ From 1547f2ec80212315d3a12195e6a94995724f6cbd Mon Sep 17 00:00:00 2001 From: Daniel Lemire Date: Tue, 23 Jun 2020 13:05:19 -0400 Subject: [PATCH 2/2] Pleasing John --- doc/basics.md | 6 ------ 1 file changed, 6 deletions(-) diff --git a/doc/basics.md b/doc/basics.md index 83dbdf97..3ce7e9be 100644 --- a/doc/basics.md +++ b/doc/basics.md @@ -47,14 +47,9 @@ Note: - Users on macOS and other platforms were default compilers do not provide C++11 compliant by default should request it with the appropriate flag (e.g., `c++ myproject.cpp simdjson.cpp`). - Visual Studio users should compile with the `_CRT_SECURE_NO_WARNINGS` flag to avoid warnings with respect to our use of standard C functions such as `fopen`. - - - Using simdjson as a CMake dependency ------------------ - - You can include the simdjson repository as a folder in your CMake project. In the parent `CMakeLists.txt` include the following lines: @@ -67,7 +62,6 @@ Elsewhere in your project, you can declare dependencies on simdjson with lines ``` add_executable(myprogram myprogram.cpp) - target_link_libraries(myprogram simdjson) ```