deploy: e9c3985f0a

features/element_access/unchecked_access.md

@@ -102,6 +102,20 @@ that the passed index is the new maximal index. Intermediate values are filled w
     `operator[]` can only be used with objects (with a string argument) or with arrays (with a numeric argument). For
     other types, a [`basic_json::type_error`](../../home/exceptions.md#jsonexceptiontype_error305) is thrown.
 
+## Performance: reserving array capacity
+
+There is no public `reserve(count)` member on `basic_json` for pre-allocating array capacity. If you are building
+a large array incrementally (e.g., via repeated `push_back()`) and know its final size ahead of time, you can
+reserve capacity via `get_ref()` to access the underlying `array_t` directly:
+
+```cpp
+json j = json::array();
+j.get_ref<json::array_t&>().reserve(1000);
+for (int i = 0; i < 1000; ++i) {
+    j.push_back(i);
+}
+```
+
 ## Summary
 
 | scenario                          | non-const value                                                                                                                                      | const value                                                                 |