deploy: e9c3985f0a

features/element_access/default_value.md

@@ -4,7 +4,8 @@
 
 In many situations, such as configuration files, missing values are not exceptional, but may be treated as if a default
 value was present. For this case, use [`value(key, default_value)`](../../api/basic_json/value.md) which takes the key
-you want to access and a default value in case there is no value stored with that key.
+you want to access and a default value in case there is no value stored with that key. This is equivalent to Python's
+`dict.get(key, default)`.
 
 ## Example
 

features/element_access/default_value/index.md

@@ -2,7 +2,7 @@
 
 ## Overview
 
-In many situations, such as configuration files, missing values are not exceptional, but may be treated as if a default value was present. For this case, use [`value(key, default_value)`](https://json.nlohmann.me/api/basic_json/value/index.md) which takes the key you want to access and a default value in case there is no value stored with that key.
+In many situations, such as configuration files, missing values are not exceptional, but may be treated as if a default value was present. For this case, use [`value(key, default_value)`](https://json.nlohmann.me/api/basic_json/value/index.md) which takes the key you want to access and a default value in case there is no value stored with that key. This is equivalent to Python's `dict.get(key, default)`.
 
 ## Example
 

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                                                                 |

features/element_access/unchecked_access/index.md

@@ -92,6 +92,18 @@ Exceptions
 
 `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`](https://json.nlohmann.me/home/exceptions/#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:
+
+```
+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                                                                                                      |