mirror of https://github.com/nlohmann/json.git
updated README
Niels
parent
bd0be5f0af
commit
4ea98517f5
53
README.md
53
README.md
|
|
@ -10,11 +10,11 @@
|
|||
|
||||
There are myriads of [JSON](http://json.org) libraries out there, and each may even have its reason to exist. Our class had these design goals:
|
||||
|
||||
- **Trivial integration**. Our whole code consists of a class in just two files: A header file `JSON.h` and a source file `JSON.cc`. That's it. No library, no subproject, no dependencies. The class is written in vanilla C++11. All in all, everything should require no adjustment of your compiler flags or project settings.
|
||||
|
||||
- **Intuitive syntax**. In languages such as Python, JSON feels like a first class data type. We used all the operator magic of modern C++ to achieve the same feeling in your code. Check out the [examples below](#examples) and the [reference](https://github.com/nlohmann/json/blob/master/Reference.md), and you know, what I mean.
|
||||
|
||||
- **Serious testing**. Our library is heavily [unit-tested](https://github.com/nlohmann/json/blob/master/test/JSON_unit.cc) and covers [100%](https://coveralls.io/r/nlohmann/json) of the code, including all exceptional behavior. Furthermore, we use [Valgrind](http://valgrind.org) to make sure no memory leaks exist.
|
||||
- **Trivial integration**. Our whole code consists of a class in just two files: A header file `JSON.h` and a source file `JSON.cc`. That's it. No library, no subproject, no dependencies. The class is written in vanilla C++11. All in all, everything should require no adjustment of your compiler flags or project settings.
|
||||
|
||||
- **Serious testing**. Our class is heavily [unit-tested](https://github.com/nlohmann/json/blob/master/test/JSON_unit.cc) and covers [100%](https://coveralls.io/r/nlohmann/json) of the code, including all exceptional behavior. Furthermore, we checked with [Valgrind](http://valgrind.org) that there are no memory leaks.
|
||||
|
||||
Other aspects were not so important to us:
|
||||
|
||||
|
|
@ -22,7 +22,7 @@ Other aspects were not so important to us:
|
|||
|
||||
- **Speed**. We currently implement the parser as naive [recursive descent parser](http://en.wikipedia.org/wiki/Recursive_descent_parser) with hand coded string handling. It is fast enough, but a [LALR-parser](http://en.wikipedia.org/wiki/LALR_parser) with a decent regular expression processor should be even faster (but would consist of more files which makes the integration harder).
|
||||
|
||||
- **Rigorous standard compliance**. We followed the [specification](http://json.org) as close as possible, but did not invest too much in a 100% compliance with respect to Unicode support. As a result, there might be edge cases of false positives and false negatives, but as long as we have a hand-written parser, we won't invest too much to be fully compliant.
|
||||
- **Rigorous standard compliance**. Any [compliant](http://json.org) JSON file can be read by our class, and any output of the class is standard-compliant. However, we do not check for some details in the format of numbers and strings. For instance, `-0` will be treated as `0` whereas the standard forbids this. Furthermore, we allow for more escape symbols in strings as the JSON specification. While this may not be a problem in reality, we are aware of it, but as long as we have a hand-written parser, we won't invest too much to be fully compliant.
|
||||
|
||||
## Integration
|
||||
|
||||
|
|
@ -55,7 +55,7 @@ j["name"] = "Niels";
|
|||
j["nothing"] = nullptr;
|
||||
|
||||
// add an object inside the object
|
||||
j["further"]["entry"] = 42;
|
||||
j["answer"]["everything"] = 42;
|
||||
|
||||
// add an array that is stored as std::vector (using an initializer list)
|
||||
j["list"] = { 1, 0, 2 };
|
||||
|
|
@ -64,16 +64,18 @@ j["list"] = { 1, 0, 2 };
|
|||
j["object"] = { {"currency", "USD"}, {"value", "42.99"} };
|
||||
```
|
||||
|
||||
### Input / Output
|
||||
Note that in all cases, the compiler derives the appropriate JSON value.
|
||||
|
||||
You can create an object by appending `_json` to a string literal:
|
||||
### Serialization / Deserialization
|
||||
|
||||
You can create an object (deserialization) by appending `_json` to a string literal:
|
||||
|
||||
```cpp
|
||||
// create object from string literal
|
||||
JSON j = "{ \"pi\": 3.141, \"happy\": true }"_json;
|
||||
```
|
||||
|
||||
You can also get a string representation:
|
||||
You can also get a string representation (serialize):
|
||||
|
||||
```cpp
|
||||
// explicit conversion to string
|
||||
|
|
@ -82,16 +84,14 @@ std::string s = j.toString();
|
|||
|
||||
The value of s could be `{"pi": 3.141, "happy": true}`, but the order of the entries in the object is not fixed.
|
||||
|
||||
You can also use streams:
|
||||
You can also use streams to serialize and deserialize:
|
||||
|
||||
```cpp
|
||||
// create object from stream
|
||||
std::stringstream ss;
|
||||
ss << "{ \"pi\": 3.141, \"happy\": true }";
|
||||
// deserialize from standard input
|
||||
JSON j;
|
||||
j << ss;
|
||||
j << std::cin;
|
||||
|
||||
// write string representation to stream
|
||||
// serialize to standard output
|
||||
std::cout << j;
|
||||
```
|
||||
|
||||
|
|
@ -102,7 +102,7 @@ These operators work for any subclasses of `std::istream` or `std::ostream`.
|
|||
We designed the JSON class to behave just like an STL container:
|
||||
|
||||
```cpp
|
||||
// create an array
|
||||
// create an array using push_back
|
||||
JSON j;
|
||||
j.push_back("foo");
|
||||
j.push_back(1);
|
||||
|
|
@ -121,9 +121,10 @@ for (auto element : j) {
|
|||
// getter/setter
|
||||
const std::string tmp = j[0];
|
||||
j[1] = 42;
|
||||
bool foo = j.at(2);
|
||||
|
||||
// other stuff
|
||||
j.size(); // 3
|
||||
j.size(); // 3 entries
|
||||
j.empty(); // false
|
||||
j.type(); // JSON::value_type::array
|
||||
j.clear(); // the array is empty again
|
||||
|
|
@ -182,7 +183,7 @@ int vi = jn.get<int>();
|
|||
|
||||
<img align="right" src="http://opensource.org/trademarks/opensource/OSI-Approved-License-100x137.png">
|
||||
|
||||
The library is licensed under the [MIT License](http://opensource.org/licenses/MIT):
|
||||
The class is licensed under the [MIT License](http://opensource.org/licenses/MIT):
|
||||
|
||||
Copyright © 2013-2014 [Niels Lohmann](http://nlohmann.me)
|
||||
|
||||
|
|
@ -191,3 +192,21 @@ Permission is hereby granted, free of charge, to any person obtaining a copy of
|
|||
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
|
||||
|
||||
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
|
||||
|
||||
## Execute unit tests
|
||||
|
||||
To compile the unit tests, you need to execute
|
||||
|
||||
```sh
|
||||
autoreconf -i
|
||||
./configure
|
||||
make
|
||||
```
|
||||
|
||||
The unit tests can then be executed with
|
||||
|
||||
```sh
|
||||
./json_unit
|
||||
```
|
||||
|
||||
For more information, have a look at the file [.travis.yml](https://github.com/nlohmann/json/blob/master/.travis.yml).
|
||||
|
|
|
|||
Loading…
Reference in New Issue