Repository files navigation

Yet anotherJSON library for C++.This one touts new C++11 features for developer-friendliness, an extremely slow-speed parser and no dependencies beyonda compliant compiler.If you love Doxygen, check out thedocumentation.

Features include (but are not necessarily limited to):

• Simple
  • Avalue should not feel terribly different from a C++ Standard Library container
  • Write valid JSON withoperator<<
  • Simple JSON parsing withparse
  • Reasonable error messages when parsing fails
  • Full support for Unicode-filled JSON (encoded in UTF-8 in C++)
• Efficient
  • Minimal overhead to store values (avalue is 16 bytes on a 64-bit platform)
  • No-throw move semantics wherever possible
• Easy
  • Convert avalue into a C++ type usingextract<T>
  • Encode a C++ type into a value usingto_json
• Safe
  • In the best case, illegal code should fail to compile
  • An illegal action should throw an exception
  • Almost all utility functions have astrong exception guarantee
• Stable
  • Worry less about upgrading -- the API and ABI will not change out from under you
• Documented
  • Consumable by human beings
  • Answers questions you might actually ask
• Compiler support
  • GCC (4.8+)
  • Clang++ (3.3+)

JSON Voorhees usesCMake as the automatic configuration software.On Linux or Mac OSX, if you haveboost,cmake,g++ andmake installed, simply:

$> cmake .$> make$> sudo make install

If you want to customize your compilation or installation, see the options inCMakeLists.txt for easy-to-useconfiguration options.

If you are on Windows, you can also use CMake if you want.However, it is probably easier to use the provided Visual Studio project files inmsvc/vs2015 to get going.Hitting F5 should perform a NuGet restore, then compile and run all the unit tests.

If you useArch Linux, JSON Voorhees is easily installable via AUR.The "latest stable" is calledjson-voorhees, while there is a "closeto tip" package calledjson-voorhees-git.With Arch, installation is as easy asyaourt json-voorhees!

Future planned features can be found on theissue tracker.

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance withthe License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed onan "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for thespecific language governing permissions and limitations under the License.

• Supported
  • GCC 4.8+
  • Clang 3.3+
• Experimental
  • MSVC 14.0 CTP5+ (Visual C++ 2015)

Like every software system ever, JSON Voorhees describes versions in 3 partsemantic versioning:${major}.${minor}.${patch}.The version components changing have very specific meanings:

• major: There are no guarantees whatsoever across major releases.
• minor: For a given minor release, all code is forward-compatible source-code compliant.That means code written against version 1.1 can be recompiled against version 1.4 and continue to work.No guarantees are made for going backwards (version 1.4 might have added new functions).
• patch: Code is ABI-compatible across patch.LibraryA built against JSON Voorhees 1.2.4 should be able to pass ajsonv::value to libraryBbuilt against JSON Voorhees 1.2.9.Any change to publicly-visible data structures or calling conventions will correspond to a bump in theminor version.

The preceding statements are not true if the version is suffixed with-preN.These values are "pre-release" and are allowed to do whatever they feel like before a release.

When developing code, follow this simple workflow to determine which version components need to change:

1. Will this change force users to change their source code?If yes, bump themajor version.
2. Will this change force users to recompile to continue to work?If yes, bump theminor version.
3. Will this change the behavior in any way?If yes, bump thepatch version.
4. Did I only change comments or rearrange code positioning (indentation, etc)?If yes, you do not need to update any part of the version.
5. Did I miss something?Yes. Go back to #1 and try again.

This library assumes youreally love UTF-8.When parsing JSON, this library happily assumes all sequences of bytes from C++ are UTF-8 encoded strings; it assumesyou also want UTF-8 encoded strings when converting from JSON in C++ land; and it assumes the non-ASCII contents of asource string should be treated as UTF-8.If you wish to use some other encoding format for yourstd::string, there is no convenient way to do that beyondconversion at every use site.There is aproposal to potentially address this.

On output, the system takes the "safe" route of using the numeric encoding for dealing with non-ASCIIstd::strings.For example, thestd::string for"Travis Göckel" ("Travis G\xc3\xb6ckel") will be encoded in JSON as"Travis G\u00f6ckel", despite the fact that the character'ö' is the most basic of the Unicode Basic MultilingualPlanes.This is generally considered the most compatible option, as (hopefully) every transport mechanism can gracefullytransmit ASCII character sequences without molestation.The drawback to this route is a needlessly lengthened resultant encoding if all components of the pipeline gracefullydeal with UTF-8.There is anoutstanding issue to address this shortcoming.

JSON Voorhees was written for a C++ programmer who wants to be productive in this modern world.What does that mean?There are aton of JSON libraries floating around touting how they are "modern" C++ and so on.But who really cares?JSON Voorhees puts the focus more on the resulting C++ than any "modern" feature set.This means the library does not skip on string encoding details like having full support forUTF-8.Are there "modern" features?Sure, but this library isnot meant to be a gallery of them -- a good API should get out of your way and let you work.

Another thing JSON Voorhees does not attempt to do is be a lightweight library; in fact, it wants to be the kitchen sinkfor anything you want to do in JSON in your C++ application.This means it isconfigurable for yourneeds.That said, the library does not depend on strange environment settings, so you can still drop the.cpp and.hpp filesinto your own project if you want.

It also includes a powerful serialization framework for converting from JSON into C++ types and back again.There is an extensibleSerialization Builder DSLto help you writing your application.The serialization framework was designed with the modern application in mind -- you will like it or your money back!

TheJSON specification only has anumber type, whereas this library haskind::integer andkind::decimal.Behavior between the two types should be fairly consistent -- comparisons between two differentkinds should behave asyou would expect (assuming you expect things likevalue(1) == value(1.0) andvalue(2.0) < value(10)).If you wish for behavior more like JavaScript, feel free to only useas_decimal().

The reason integer and decimal are not a single type is because of how people tend to use JSON in C++.If you look at projects that consume JSON, they make a distinction between integer and decimal values.Even in specification land, a distinction between the numeric type is pretty normal (for example:Swagger).To ultimately answer the question: integer and decimal are distinct types for the convenience of users.

TheJSON specification doesnot have support for non-finite floating-point numbers likeNaN and infinity.This means thevalue defined withobject({ { "nan", std::nan("") }, { "infinity", INFINITY } }) to get serialized as{ "nan": null, "infinity": null }.While this seems to constitute a loss of information, not doing this would lead to the encoder outputting invalid JSONtext, which is completely unacceptable (unfortunately, this is avery common mistake in JSON libraries).If you want to check that there will be no information loss when encoding, use the utility funcitonvalidate.

Why not throw when encoding?One could imagine theencoder::encode throwing something like anencode_error instead of outputtingnull to thestream.However, that would makeoperator<< a potentially-throwing operation, which is extremely uncommon and would be verysurprizing (imagine if you tried to log avalue and it threw).

Why not throw when constructing thevalue?Instead of waiting for encoding time to do anything about the problem, the library could attack the issue at the sourceand throw an exception if someone saysvalue(INFINITY).This was not chosen as the behavior, because non-finite values are only an issue in the string representation, which isnot a problem if thevalue is never encoded.You are free to use this JSON library withoutparse andencode, so it should not prevent an action simply becausesomeonemight useencode.

If you are looking through the implementation, you will find a ton of places where there aredefault cases inswitchstatements that should be impossible to hit without memory corruption.This is because it is unclear what should happen when the library detects something like an invalidkind.The library couldassert, but that seems overbearing when there is a reasonable option to fall back to.Alternatively, the library could throw in these cases, but that leads to innocuous-looking operations likex == ybeing able to throw, which is somewhat disconcerning.

I would beFlattr-ed!

Not really...