Design Rationale

The JSON parser is incremental because that is a versatile building-block for network wire protocols. Many other JSON parsers are restricted to the Document Object Model, wherein the entire JSON input is parsed into a parse tree before you can operate on it. If the JSON input should end up in your own C++ data structures, then the parse tree becomes an unnecessary intermediate step. In this case your program becomes both slower and consumes more memory.

A JSON DOM can be created using the incremental parser and Boost.Serialization.

The ability of json::reader to read the input one token at the time makes it work like an iterator. The design is build around the more traditional Iterator design pattern as described in the Gang-of-Four book, instead of C++ iterators.

JSON numbers are arithmetic - there is no distinction between integer and floating-point numbers. C++ does make that distinction, so json::reader will identify numbers either as integers (identified by the json::token::symbol::integer token) if they consist solely of digits, or as floating-point numbers (identified by the json::token::symbol::number token) if they contain a decimal-point or an exponent.

Regardless of how a number was identified, it can be converted using json::reader::value<T>() as either a C integer or floating-point number. This means that integer numbers that are too big to fit into a C integer type such as std::intmax_t can be read as a floating-point number.