You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Resolved conflicts by regenerating the amalgamated single-header
files (simdjson.h, simdjson.cpp, and singleheader.zip) using the
amalgamate.py script after merging latest changes from master.
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
*[Using simdjson with package managers](#using-simdjson-with-package-managers)
12
+
*[Using simdjson as a CMake dependency](#using-simdjson-as-a-cmake-dependency)
13
+
*[Versions](#versions)
14
+
*[The basics: loading and parsing JSON documents](#the-basics--loading-and-parsing-json-documents)
15
+
*[Documents are iterators](#documents-are-iterators)
16
+
+[Parser, document and JSON scope](#parser--document-and-json-scope)
17
+
*[string_view](#string-view)
18
+
*[Avoiding pitfalls: enable development checks](#avoiding-pitfalls--enable-development-checks)
19
+
*[Using the parsed JSON](#using-the-parsed-json)
20
+
+[Using the parsed JSON: additional examples](#using-the-parsed-json--additional-examples)
21
+
*[Adding support for custom types](#adding-support-for-custom-types)
22
+
+[1. Specialize `simdjson::ondemand::value::get` to get custom types (pre-C++20)](#1-specialize--simdjson--ondemand--value--get--to-get-custom-types--pre-c--20-)
23
+
+[2. Use `tag_invoke` for custom types (C++20)](#2-use--tag-invoke--for-custom-types--c--20-)
24
+
+[3. Using static reflection (C++26)](#3-using-static-reflection--c--26-)
25
+
*[Minifying JSON strings without parsing](#minifying-json-strings-without-parsing)
@@ -826,7 +829,7 @@ There are 3 main ways provided by simdjson to deserialize a value into a custom
826
829
1. Specialize `simdjson::ondemand::document::get` for the whole document
827
830
2. Specialize `simdjson::ondemand::value::get` for each value
828
831
2. Using `tag_invoke`*(the recommended way if your system supports C++20 or better)*
829
-
3. Using static reflectioin (requires C++26 or better)
832
+
3. Using static reflection (requires C++26 or better)
830
833
831
834
We describe all of them in the following sections. Most users who have systems compatible with
832
835
C++20 or better should skip ahead to [using `tag_invoke` for custom types (C++20)](#2-use-tag_invoke-for-custom-types-c20) as it is more powerful and simpler.
@@ -1140,7 +1143,7 @@ struct Car {
1140
1143
};
1141
1144
```
1142
1145
1143
-
Observe how we defined the class to use types that simdjson does not directly support (`float`, `int`).
1146
+
Observe how we define the class to use types that simdjson does not directly support (`float`, `int`).
1144
1147
With C++20 support, the library grabs from the JSON the generic type (`double`, `int`) and then it
1145
1148
casts it automatically.
1146
1149
@@ -1355,11 +1358,12 @@ your code with the `SIMDJSON_STATIC_REFLECTION` macro set:
1355
1358
```
1356
1359
1357
1360
Then you can deserialize a type such as `Car` automatically:
+[Without `string_buffer` instance but with explicit error handling](#without--string-buffer--instance-but-with-explicit-error-handling)
9
17
10
18
Overview: string_builder
11
19
---------------------------
12
20
13
21
The string_builder class is a low-level utility for constructing JSON strings representing documents. It is optimized for performance, potentially leveraging kernel-specific features like SIMD instructions for tasks such as string escaping. This class supports atomic types (e.g., booleans, numbers, strings) but does not handle composed types directly (like arrays or objects).
22
+
Note that JSON strings are always encoded as UTF-8.
14
23
15
24
An `string_builder` is created with an initial buffer capacity (e.g., 1kB). The memory
16
-
is reallocated when needed. It has the following methods to add content to the string:
25
+
is reallocated when needed.
26
+
The efficiency of `string_builder` stems from its internal use of a resizable array or buffer. When you append data, it adds the characters to this buffer, resizing it only when necessary, typically in a way that minimizes reallocations. This approach contrasts with regular string concatenation, where each operation creates a new string, copying all previous content, leading to quadratic time complexity for repeated concatenations.
27
+
28
+
29
+
It has the following methods to add content to the string:
17
30
18
31
19
32
-`append(number_type v)`: Appends a number (including booleans) to the JSON buffer. Booleans are converted to the strings "false" or "true". Numbers are formatted according to the JSON standard, with floating-point numbers using the shortest representation that accurately reflects the value.
@@ -32,6 +45,9 @@ After writting the content, if you have reasons to believe that the content migh
32
45
33
46
-`validate_unicode()`: Checks if the content in the JSON buffer is valid UTF-8. Returns: true if the content is valid UTF-8, false otherwise.
34
47
48
+
You might need to do unicode validation if you have strings in your data structures containing
49
+
malformed UTF-8.
50
+
35
51
Once you are satisfied, you can recover the string as follows:
36
52
37
53
-`operator std::string()`: Converts the JSON buffer to an std::string. (Might throw if an error occurred.)
The `string_builder` constructor takes an optional parameter which specifies the initial
113
+
memory allocation in byte. If you know approximately the size of your JSON output, you can
114
+
pass this value as a parameter (e.g., `simdjson::builder::string_builder sb{1233213}`).
115
+
116
+
The `string_builder` might throw an exception in case of error when you cast it result to `std::string_view`. If you wish to avoid exceptions, you can use the following programming pattern:
117
+
118
+
```cpp
119
+
std::string_view p;
120
+
if(sb.view().get(p)) {
121
+
return false; // there was an error
90
122
}
91
123
```
92
124
125
+
In all cases, the `std::string_view` instance depends the corresponding `string_builder` instance.
126
+
93
127
C++26 static reflection
94
128
------------------------
95
129
130
+
Static reflection (or compile-time reflection) in C++26 introduces a powerful compile-time mechanism that allows a program to inspect and manipulate its own structure, such as types, variables, functions, and other program elements, during compilation. Unlike runtime reflection in languages like Java or Python, C++26’s static reflection operates entirely at compile time, aligning with C++’s emphasis on zero-overhead abstractions and high performance. It means
131
+
that you can delegate much of the work to the library.
96
132
If you have a compiler with support C++26 static reflection, you can compile
97
133
your code with the `SIMDJSON_STATIC_REFLECTION` macro set:
98
134
@@ -106,21 +142,55 @@ And then you can append your data structures to a `string_builder` instance
106
142
automatically. In most cases, it should work automatically:
107
143
108
144
```cpp
145
+
structCar {
146
+
std::string make;
147
+
std::string model;
148
+
int64_t year;
149
+
std::vector<double> tire_pressure;
150
+
};
151
+
109
152
bool car_test() {
110
153
simdjson::builder::string_builder sb;
111
154
Car c = {"Toyota", "Corolla", 2017, {30.0,30.2,30.513,30.79}};
0 commit comments