lib/json
1
0
Fork 0
mirror of https://github.com/nlohmann/json.git synced 2025-07-28 12:02:00 +03:00
Code Activity

Merge pull request #2312 from nlohmann/docs

Browse Source 
Update documentation
This commit is contained in:
Niels Lohmann
2020-07-26 10:06:01 +02:00
committed by GitHub
parent 808aca41aa a34070d36a
commit 67ed63b196
21 changed files with 547 additions and 60 deletions
Download Patch File Download Diff File Expand all files Collapse all files

37
doc/mkdocs/docs/home/faq.md
View File

@ -2,31 +2,6 @@
## Limitations
### Comments
!!! question "Questions"
- Why does the library not support comments?
- Can you add support for JSON5/JSONC/HOCON so that comments are supported?
This library does not support comments. It does so for three reasons:
1. Comments are not part of the [JSON specification](https://tools.ietf.org/html/rfc8259). You may argue that `//` or `/* */` are allowed in JavaScript, but JSON is not JavaScript.
2. This was not an oversight: Douglas Crockford [wrote on this](https://plus.google.com/118095276221607585885/posts/RK8qyGVaGSr) in May 2012:
> I removed comments from JSON because I saw people were using them to hold parsing directives, a practice which would have destroyed interoperability. I know that the lack of comments makes some people sad, but it shouldn't.
> Suppose you are using JSON to keep configuration files, which you would like to annotate. Go ahead and insert all the comments you like. Then pipe it through JSMin before handing it to your JSON parser.
3. It is dangerous for interoperability if some libraries would add comment support while others don't. Please check [The Harmful Consequences of the Robustness Principle](https://tools.ietf.org/html/draft-iab-protocol-maintenance-01) on this.
This library will not support comments in the future. If you wish to use comments, I see three options:
1. Strip comments before using this library.
2. Use a different JSON library with comment support.
3. Use a format that natively supports comments (e.g., YAML or JSON5).
### Relaxed parsing
!!! question
@ -69,18 +44,6 @@ No, this is not possible. See <https://github.com/nlohmann/json/issues/932> for
## Serialization issues
### Order of object keys
!!! question "Questions"
- Why are object keys sorted?
- Why is the insertion order of object keys not preserved?
By default, the library does not preserve the **insertion order of object elements**. This is standards-compliant, as the [JSON standard](https://tools.ietf.org/html/rfc8259.html) defines objects as "an unordered collection of zero or more name/value pairs".
If you do want to preserve the insertion order, you can specialize the object type with containers like [`tsl::ordered_map`](https://github.com/Tessil/ordered-map) ([integration](https://github.com/nlohmann/json/issues/546#issuecomment-304447518)) or [`nlohmann::fifo_map`](https://github.com/nlohmann/fifo_map) ([integration](https://github.com/nlohmann/json/issues/485#issuecomment-333652309)).
### Number precision
!!! question

2
doc/mkdocs/docs/home/license.md
View File

@ -4,7 +4,7 @@
The class is licensed under the [MIT License](http://opensource.org/licenses/MIT):
Copyright &copy; 2013-2019 [Niels Lohmann](http://nlohmann.me)
Copyright &copy; 2013-2020 [Niels Lohmann](http://nlohmann.me)
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: