deploy: 94fe31eb9b

features/arbitrary_types/index.md

@@ -54,7 +54,7 @@ assert(p == p2);
 To make this work with one of your types, you only need to provide two functions:
 
 ```
-using json = nlohmann::json;
+using nlohmann::json;
 
 namespace ns {
     void to_json(json& j, const person& p) {
@@ -86,7 +86,7 @@ Example: serialize a `person` to JSON with `to_json`
 #include <iostream>
 #include <nlohmann/json.hpp>
 
-using json = nlohmann::json;
+using nlohmann::json;
 
 namespace ns
 {
@@ -113,7 +113,7 @@ int main()
 
     json j = p;
 
-    std::cout << j << std::endl;
+    std::cout << j << '\n';
 }
 ```
 
@@ -129,7 +129,7 @@ Example: deserialize a `person` from JSON with `from_json`
 #include <iostream>
 #include <nlohmann/json.hpp>
 
-using json = nlohmann::json;
+using nlohmann::json;
 
 namespace ns
 {
@@ -161,7 +161,7 @@ int main()
 
     auto p = j.get<ns::person>();
 
-    std::cout << p.name << " (" << p.age << ") lives in " << p.address << std::endl;
+    std::cout << p.name << " (" << p.age << ") lives in " << p.address << '\n';
 }
 ```
 
@@ -409,7 +409,7 @@ Example: `get()` for a non-default-constructible type
 #include <iostream>
 #include <nlohmann/json.hpp>
 
-using json = nlohmann::json;
+using nlohmann::json;
 
 namespace ns
 {
@@ -457,7 +457,7 @@ int main()
 
     auto p = j.get<ns::person>();
 
-    std::cout << p.name << " (" << p.age << ") lives in " << p.address << std::endl;
+    std::cout << p.name << " (" << p.age << ") lives in " << p.address << '\n';
 }
 ```
 
@@ -498,6 +498,18 @@ namespace nlohmann {
 }
 ```
 
+## Why isn't my `to_json` or `from_json` found?
+
+The library calls `to_json` and `from_json` without qualification, so the compiler finds them by [argument-dependent lookup](https://en.cppreference.com/w/cpp/language/adl) in the namespace of the type, or in the namespaces of its template arguments. The usual reasons for a function that is "not found" are:
+
+- **The type is an alias of a standard type.** After `using Hash = std::array<std::uint8_t, 6>;` the type *is* `std::array<std::uint8_t, 6>`, which lives in namespace `std`. A `to_json(json&, const Hash&)` in your namespace is never selected. Either give the type its own identity, for example `struct Hash : std::array<std::uint8_t, 6> {};` (the function is then found in `Hash`'s namespace), or specialize [`adl_serializer<Hash>`](#how-do-i-convert-third-party-types).
+- **The function is in the wrong namespace.** It must be in the namespace of the type (a global type needs a global function), not in the namespace of the code that calls the conversion. Specializations of `adl_serializer` belong in namespace `nlohmann`.
+- **It is declared too late.** A conversion can only use what has been declared when it is instantiated. If `json j = std::vector<third_party::string>{...};` appears before the `adl_serializer` specialization, the compiler reports an error such as "explicit specialization of `adl_serializer<...>` after instantiation". Put the specialization in a small header that every file includes **before** it uses the type with `json`.
+- **It is a template.** For `template <class T> struct box`, write `template <class T> void to_json(json&, const box<T>&)`, not an overload for one `T`.
+- **It worked by accident.** Some versions found `to_json` overloads in `nlohmann::detail` through argument-dependent lookup of the base class of `basic_json`. Do not rely on this; it is not part of the interface.
+
+For smart pointers, class hierarchies, `std::variant`, and `std::chrono`, see [Recipes for common types](https://json.nlohmann.me/features/type_recipes/index.md).
+
 ## Why can't I convert to/from `std::any`?
 
 `std::any` is intentionally excluded from `get<T>()`/generic conversion support, so `get<std::any>()` and containers like `std::map<std::string, std::any>` fail to compile by design -- there is no way to know, from a `json` value alone, which concrete type to store inside the `std::any`. To work with heterogeneous JSON values, dispatch on the value's type manually and construct the `std::any` (or extract from it) yourself:
@@ -587,6 +599,7 @@ struct bad_serializer
 
 ## See also
 
+- [Recipes for common types](https://json.nlohmann.me/features/type_recipes/index.md) - smart pointers, class hierarchies, `std::variant`, and `std::chrono`
 - [Converting values](https://json.nlohmann.me/features/conversions/index.md) - the general overview of `get`/`get_to` and implicit conversions
 - [Specializing enum conversion](https://json.nlohmann.me/features/enum_conversion/index.md) - map enums to JSON strings instead of integers
 - [Supported macros](https://json.nlohmann.me/features/macros/index.md) - reference for `NLOHMANN_DEFINE_TYPE_*` and related macros