deploy: 78ddd95794

features/arbitrary_types.md

@@ -79,6 +79,7 @@ Some important things:
 * When using `get<your_type>()`, `your_type` **MUST** be [DefaultConstructible](https://en.cppreference.com/w/cpp/named_req/DefaultConstructible). (There is a way to bypass this requirement described later.)
 * In function `from_json`, use function [`at()`](../api/basic_json/at.md) to access the object values rather than `operator[]`. In case a key does not exist, `at` throws an exception that you can handle, whereas `operator[]` exhibits undefined behavior.
 * You do not need to add serializers or deserializers for STL types like `std::vector`: the library already implements these.
+* If you control the type, consider defining `to_json`/`from_json` as `friend` functions inside the class ("hidden friends"). Argument-dependent lookup then only finds them for your type, which also avoids a [GCC < 11 compilation error](../home/faq.md#incomplete-detector-type-with-gcc-11).
 
 ??? example "Example: serialize a `person` to JSON with `to_json`"
 

features/arbitrary_types/index.md

@@ -78,6 +78,7 @@ Some important things:
 - When using `get<your_type>()`, `your_type` **MUST** be [DefaultConstructible](https://en.cppreference.com/w/cpp/named_req/DefaultConstructible). (There is a way to bypass this requirement described later.)
 - In function `from_json`, use function [`at()`](https://json.nlohmann.me/api/basic_json/at/index.md) to access the object values rather than `operator[]`. In case a key does not exist, `at` throws an exception that you can handle, whereas `operator[]` exhibits undefined behavior.
 - You do not need to add serializers or deserializers for STL types like `std::vector`: the library already implements these.
+- If you control the type, consider defining `to_json`/`from_json` as `friend` functions inside the class ("hidden friends"). Argument-dependent lookup then only finds them for your type, which also avoids a [GCC < 11 compilation error](https://json.nlohmann.me/home/faq/#incomplete-detector-type-with-gcc-11).
 
 Example: serialize a `person` to JSON with `to_json`
 

home/faq.md

@@ -305,6 +305,51 @@ Only very old NDKs (before r18), which defaulted to GCC and `gnustl`, lacked C++
 `std::to_string`. If you run into this, update to a current NDK.
 
 
+### Incomplete `detector` type with GCC < 11
+
+!!! question
+
+    Why does GCC 10 or older fail with `invalid use of incomplete type 'struct nlohmann::detail::detector<..., to_json_function, ...>'` for a type that holds an `optional` member?
+
+This happens with GCC 10 and older in C++11/C++14 mode when all of these hold:
+
+- a class `Holder` has an `optional<Dummy>` member (e.g., `boost::optional`),
+- `Dummy` has a constructor taking a `json` value, and
+- `to_json` for `Holder` is a free function in the namespace of `Dummy`.
+
+```cpp
+class Dummy {
+  public:
+    explicit Dummy(const nlohmann::json& j);
+};
+
+class Holder {
+    boost::optional<Dummy> d;
+};
+
+void to_json(nlohmann::json& j, const Holder& h);  // triggers the error
+```
+
+To decide whether `Dummy` is copyable, the compiler checks whether a `Dummy` can be converted to `json`. That check
+looks up `to_json` via argument-dependent lookup, finds the unrelated `to_json` for `Holder`, and eventually asks again
+whether `Dummy` is copyable. GCC before version 11 turns this cycle into a hard error; GCC 11 and later, Clang, and
+C++17 mode compile the code. The same error shows up without this library whenever a constrained converting constructor
+is involved, so the library can't avoid it.
+
+To work around this, define `to_json` (and `from_json`) as a *hidden friend* inside the class. That way,
+argument-dependent lookup only finds it for `Holder`:
+
+```cpp
+class Holder {
+    boost::optional<Dummy> d;
+
+    friend void to_json(nlohmann::json& j, const Holder& h) { /* ... */ }
+};
+```
+
+The [`NLOHMANN_DEFINE_TYPE_INTRUSIVE`](../api/macros/nlohmann_define_type_intrusive.md) macros define hidden friends as
+well. See [#3669](https://github.com/nlohmann/json/issues/3669) for details.
+
 ### Missing STL function
 
 !!! question "Questions"

home/faq/index.md

@@ -273,6 +273,45 @@ Since [NDK r18](https://github.com/android/ndk/wiki/Changelog-r18) (2018), GCC a
 
 Only very old NDKs (before r18), which defaulted to GCC and `gnustl`, lacked C++11 library features such as `std::to_string`. If you run into this, update to a current NDK.
 
+### Incomplete `detector` type with GCC < 11
+
+Question
+
+Why does GCC 10 or older fail with `invalid use of incomplete type 'struct nlohmann::detail::detector<..., to_json_function, ...>'` for a type that holds an `optional` member?
+
+This happens with GCC 10 and older in C++11/C++14 mode when all of these hold:
+
+- a class `Holder` has an `optional<Dummy>` member (e.g., `boost::optional`),
+- `Dummy` has a constructor taking a `json` value, and
+- `to_json` for `Holder` is a free function in the namespace of `Dummy`.
+
+```
+class Dummy {
+  public:
+    explicit Dummy(const nlohmann::json& j);
+};
+
+class Holder {
+    boost::optional<Dummy> d;
+};
+
+void to_json(nlohmann::json& j, const Holder& h);  // triggers the error
+```
+
+To decide whether `Dummy` is copyable, the compiler checks whether a `Dummy` can be converted to `json`. That check looks up `to_json` via argument-dependent lookup, finds the unrelated `to_json` for `Holder`, and eventually asks again whether `Dummy` is copyable. GCC before version 11 turns this cycle into a hard error; GCC 11 and later, Clang, and C++17 mode compile the code. The same error shows up without this library whenever a constrained converting constructor is involved, so the library can't avoid it.
+
+To work around this, define `to_json` (and `from_json`) as a *hidden friend* inside the class. That way, argument-dependent lookup only finds it for `Holder`:
+
+```
+class Holder {
+    boost::optional<Dummy> d;
+
+    friend void to_json(nlohmann::json& j, const Holder& h) { /* ... */ }
+};
+```
+
+The [`NLOHMANN_DEFINE_TYPE_INTRUSIVE`](https://json.nlohmann.me/api/macros/nlohmann_define_type_intrusive/index.md) macros define hidden friends as well. See [#3669](https://github.com/nlohmann/json/issues/3669) for details.
+
 ### Missing STL function
 
 Questions