mirror of
https://github.com/nlohmann/json
synced 2024-11-21 19:50:04 +00:00
Make certain usage patterns more prominent in the README (#3557)
* Make certain usage patterns more prominent in the README We use this library extensively where I work. After pairing with many teammates, I've learned that one common stumbling point when using this library is how to first get a JSON value in the first place (because once they have a variable of type `json` in hand, the API is intuitive and mostly does what you expect). With that in mind, I've added two subsections to the top of the Examples section: how to read JSON from a file, and how to hardcode a JSON literal. I understand that these are already documented elsewhere in the Examples section, and so these new subsections are technically redundant. But to defend this choice: - Redundancy in docs is actually good, because not everyone consumes docs in the same way or in the same order. - Having these things called out explicitly in isolation encourages people to get something working faster. In later sections, these examples are presented alongside many other options. Having to choose between alternatives gets in the way of quickly prototyping something. If you have further suggestions for how to improve or modify these docs I'm open to them. The changes included here would really make a huge improvement in the productivity of newer members of my team using this library. * Remove old TOC entry * Put the section back * Another tweak
This commit is contained in:
parent
a15683e348
commit
2a9ae2b487
63
README.md
63
README.md
@ -24,6 +24,8 @@
|
||||
- [Sponsors](#sponsors)
|
||||
- [Support](#support) ([documentation](https://json.nlohmann.me), [FAQ](https://json.nlohmann.me/home/faq/), [discussions](https://github.com/nlohmann/json/discussions), [API](https://json.nlohmann.me/api/basic_json/), [bug issues](https://github.com/nlohmann/json/issues))
|
||||
- [Examples](#examples)
|
||||
- [Read JSON from a file](#read-json-from-a-file)
|
||||
- [Creating `json` objects from JSON literals](#creating-json-objects-from-json-literals)
|
||||
- [JSON as first-class data type](#json-as-first-class-data-type)
|
||||
- [Serialization / Deserialization](#serialization--deserialization)
|
||||
- [STL-like access](#stl-like-access)
|
||||
@ -98,7 +100,66 @@ There is also a [**docset**](https://github.com/Kapeli/Dash-User-Contributions/t
|
||||
|
||||
## Examples
|
||||
|
||||
Beside the examples below, you may want to check the [documentation](https://json.nlohmann.me/) where each function contains a separate code example (e.g., check out [`emplace()`](https://json.nlohmann.me/api/basic_json/emplace/)). All [example files](https://github.com/nlohmann/json/tree/develop/docs/examples) can be compiled and executed on their own (e.g., file [emplace.cpp](https://github.com/nlohmann/json/blob/develop/docs/examples/emplace.cpp)).
|
||||
Here are some examples to give you an idea how to use the class.
|
||||
|
||||
Beside the examples below, you may want to:
|
||||
|
||||
→ Check the [documentation](https://json.nlohmann.me/)\
|
||||
→ Browse the [standalone example files](https://github.com/nlohmann/json/tree/develop/docs/examples)
|
||||
|
||||
Every API function (documented in the [API Documentation](https://json.nlohmann.me/api/basic_json/)) has a corresponding standalone example file. For example, the [`emplace()`](https://json.nlohmann.me/api/basic_json/emplace/) function has a matching [emplace.cpp](https://github.com/nlohmann/json/blob/develop/docs/examples/emplace.cpp) example file.
|
||||
|
||||
### Read JSON from a file
|
||||
|
||||
The `json` class provides an API for manipulating a JSON value. To create a `json` object by reading a JSON file:
|
||||
|
||||
```cpp
|
||||
#include <fstream>
|
||||
#include <nlohmann/json.hpp>
|
||||
using json = nlohmann::json;
|
||||
|
||||
// ...
|
||||
|
||||
std::ifstream f("example.json");
|
||||
json data = json::parse(f);
|
||||
```
|
||||
|
||||
### Creating `json` objects from JSON literals
|
||||
|
||||
Assume you want to create hard-code this literal JSON value in a file, as a `json` object:
|
||||
|
||||
```json
|
||||
{
|
||||
"pi": 3.141,
|
||||
"happy": true
|
||||
}
|
||||
```
|
||||
|
||||
There are various options:
|
||||
|
||||
```cpp
|
||||
// Using (raw) string literals and json::parse
|
||||
json ex1 = json::parse(R"(
|
||||
{
|
||||
"pi": 3.141,
|
||||
"happy": true
|
||||
}
|
||||
)");
|
||||
|
||||
// Using user-defined (raw) string literals
|
||||
json ex2 = R"(
|
||||
{
|
||||
"pi": 3.141,
|
||||
"happy": true
|
||||
}
|
||||
)"_json;
|
||||
|
||||
// Using initializer lists
|
||||
json ex3 = {
|
||||
{"happy", true},
|
||||
{"pi", 3.141},
|
||||
};
|
||||
```
|
||||
|
||||
### JSON as first-class data type
|
||||
|
||||
|
Loading…
Reference in New Issue
Block a user