"Fossies" - the Fresh Open Source Software Archive  

Source code changes of the file "doc/sax.md" between
rapidjson-1.0.2.tar.gz and rapidjson-1.1.0.tar.gz

About: RapidJSON is a fast JSON parser/generator for C++ with both SAX/DOM style API.

sax.md  (rapidjson-1.0.2)	:	sax.md  (rapidjson-1.1.0)
skipping to change at line 62		skipping to change at line 62
These events can be easily matched with the JSON, except some event parameters n eed further explanation. Let's see the `simplereader` example which produces exa ctly the same output as above:		These events can be easily matched with the JSON, except some event parameters n eed further explanation. Let's see the `simplereader` example which produces exa ctly the same output as above:
~~~~~~~~~~cpp		~~~~~~~~~~cpp
#include "rapidjson/reader.h"		#include "rapidjson/reader.h"
#include <iostream>		#include <iostream>
using namespace rapidjson;		using namespace rapidjson;
using namespace std;		using namespace std;
struct MyHandler {		struct MyHandler : public BaseReaderHandler<UTF8<>, MyHandler> {
bool Null() { cout << "Null()" << endl; return true; }		bool Null() { cout << "Null()" << endl; return true; }
bool Bool(bool b) { cout << "Bool(" << boolalpha << b << ")" << endl; return true; }		bool Bool(bool b) { cout << "Bool(" << boolalpha << b << ")" << endl; return true; }
bool Int(int i) { cout << "Int(" << i << ")" << endl; return true; }		bool Int(int i) { cout << "Int(" << i << ")" << endl; return true; }
bool Uint(unsigned u) { cout << "Uint(" << u << ")" << endl; return true; }		bool Uint(unsigned u) { cout << "Uint(" << u << ")" << endl; return true; }
bool Int64(int64_t i) { cout << "Int64(" << i << ")" << endl; return true; }		bool Int64(int64_t i) { cout << "Int64(" << i << ")" << endl; return true; }
bool Uint64(uint64_t u) { cout << "Uint64(" << u << ")" << endl; return true ; }		bool Uint64(uint64_t u) { cout << "Uint64(" << u << ")" << endl; return true ; }
bool Double(double d) { cout << "Double(" << d << ")" << endl; return true; }		bool Double(double d) { cout << "Double(" << d << ")" << endl; return true; }
bool String(const char* str, SizeType length, bool copy) {		bool String(const char* str, SizeType length, bool copy) {
cout << "String(" << str << ", " << length << ", " << boolalpha << copy << ")" << endl;		cout << "String(" << str << ", " << length << ", " << boolalpha << copy << ")" << endl;
return true;		return true;
skipping to change at line 109		skipping to change at line 109
~~~~~~~~~~cpp		~~~~~~~~~~cpp
class Handler {		class Handler {
bool Null();		bool Null();
bool Bool(bool b);		bool Bool(bool b);
bool Int(int i);		bool Int(int i);
bool Uint(unsigned i);		bool Uint(unsigned i);
bool Int64(int64_t i);		bool Int64(int64_t i);
bool Uint64(uint64_t i);		bool Uint64(uint64_t i);
bool Double(double d);		bool Double(double d);
		bool RawNumber(const Ch* str, SizeType length, bool copy);
bool String(const Ch* str, SizeType length, bool copy);		bool String(const Ch* str, SizeType length, bool copy);
bool StartObject();		bool StartObject();
bool Key(const Ch* str, SizeType length, bool copy);		bool Key(const Ch* str, SizeType length, bool copy);
bool EndObject(SizeType memberCount);		bool EndObject(SizeType memberCount);
bool StartArray();		bool StartArray();
bool EndArray(SizeType elementCount);		bool EndArray(SizeType elementCount);
};		};
~~~~~~~~~~		~~~~~~~~~~
`Null()` is called when the `Reader` encounters a JSON null value.		`Null()` is called when the `Reader` encounters a JSON null value.
`Bool(bool)` is called when the `Reader` encounters a JSON true or false value.		`Bool(bool)` is called when the `Reader` encounters a JSON true or false value.
When the `Reader` encounters a JSON number, it chooses a suitable C++ type mappi ng. And then it calls *one* function out of `Int(int)`, `Uint(unsigned)`, `Int64 (int64_t)`, `Uint64(uint64_t)` and `Double(double)`.		When the `Reader` encounters a JSON number, it chooses a suitable C++ type mappi ng. And then it calls *one* function out of `Int(int)`, `Uint(unsigned)`, `Int64 (int64_t)`, `Uint64(uint64_t)` and `Double(double)`. If `kParseNumbersAsStrings` is enabled, `Reader` will always calls `RawNumber()` instead.
`String(const char* str, SizeType length, bool copy)` is called when the `Reader ` encounters a string. The first parameter is pointer to the string. The second parameter is the length of the string (excluding the null terminator). Note that RapidJSON supports null character `'\0'` inside a string. If such situation hap pens, `strlen(str) < length`. The last `copy` indicates whether the handler need s to make a copy of the string. For normal parsing, `copy = true`. Only when *in situ* parsing is used, `copy = false`. And beware that, the character type depen ds on the target encoding, which will be explained later.		`String(const char* str, SizeType length, bool copy)` is called when the `Reader ` encounters a string. The first parameter is pointer to the string. The second parameter is the length of the string (excluding the null terminator). Note that RapidJSON supports null character `'\0'` inside a string. If such situation hap pens, `strlen(str) < length`. The last `copy` indicates whether the handler need s to make a copy of the string. For normal parsing, `copy = true`. Only when *in situ* parsing is used, `copy = false`. And beware that, the character type depen ds on the target encoding, which will be explained later.
When the `Reader` encounters the beginning of an object, it calls `StartObject() `. An object in JSON is a set of name-value pairs. If the object contains member s it first calls `Key()` for the name of member, and then calls functions depend ing on the type of the value. These calls of name-value pairs repeats until call ing `EndObject(SizeType memberCount)`. Note that the `memberCount` parameter is just an aid for the handler, user may not need this parameter.		When the `Reader` encounters the beginning of an object, it calls `StartObject() `. An object in JSON is a set of name-value pairs. If the object contains member s it first calls `Key()` for the name of member, and then calls functions depend ing on the type of the value. These calls of name-value pairs repeats until call ing `EndObject(SizeType memberCount)`. Note that the `memberCount` parameter is just an aid for the handler, user may not need this parameter.
Array is similar to object but simpler. At the beginning of an array, the `Reade r` calls `BeginArary()`. If there is elements, it calls functions according to t he types of element. Similarly, in the last call `EndArray(SizeType elementCount )`, the parameter `elementCount` is just an aid for the handler.		Array is similar to object but simpler. At the beginning of an array, the `Reade r` calls `BeginArary()`. If there is elements, it calls functions according to t he types of element. Similarly, in the last call `EndArray(SizeType elementCount )`, the parameter `elementCount` is just an aid for the handler.
Every handler functions returns a `bool`. Normally it should returns `true`. If the handler encounters an error, it can return `false` to notify event publisher to stop further processing.		Every handler functions returns a `bool`. Normally it should returns `true`. If the handler encounters an error, it can return `false` to notify event publisher to stop further processing.
For example, when we parse a JSON with `Reader` and the handler detected that th e JSON does not conform to the required schema, then the handler can return `fal se` and let the `Reader` stop further parsing. And the `Reader` will be in error state with error code `kParseErrorTermination`.		For example, when we parse a JSON with `Reader` and the handler detected that th e JSON does not conform to the required schema, then the handler can return `fal se` and let the `Reader` stop further parsing. And the `Reader` will be in error state with error code `kParseErrorTermination`.
skipping to change at line 161		skipping to change at line 162
The `Reader` uses UTF-8 as both source and target encoding. The source encoding means the encoding in the JSON stream. The target encoding means the encoding of the `str` parameter in `String()` calls. For example, to parse a UTF-8 stream a nd outputs UTF-16 string events, you can define a reader by:		The `Reader` uses UTF-8 as both source and target encoding. The source encoding means the encoding in the JSON stream. The target encoding means the encoding of the `str` parameter in `String()` calls. For example, to parse a UTF-8 stream a nd outputs UTF-16 string events, you can define a reader by:
~~~~~~~~~~cpp		~~~~~~~~~~cpp
GenericReader<UTF8<>, UTF16<> > reader;		GenericReader<UTF8<>, UTF16<> > reader;
~~~~~~~~~~		~~~~~~~~~~
Note that, the default character type of `UTF16` is `wchar_t`. So this `reader`n eeds to call `String(const wchar_t*, SizeType, bool)` of the handler.		Note that, the default character type of `UTF16` is `wchar_t`. So this `reader`n eeds to call `String(const wchar_t*, SizeType, bool)` of the handler.
The third template parameter `Allocator` is the allocator type for internal data structure (actually a stack).		The third template parameter `Allocator` is the allocator type for internal data structure (actually a stack).
## Parsing {#Parsing}		## Parsing {#SaxParsing}
The one and only one function of `Reader` is to parse JSON.		The one and only one function of `Reader` is to parse JSON.
~~~~~~~~~~cpp		~~~~~~~~~~cpp
template <unsigned parseFlags, typename InputStream, typename Handler>		template <unsigned parseFlags, typename InputStream, typename Handler>
bool Parse(InputStream& is, Handler& handler);		bool Parse(InputStream& is, Handler& handler);
// with parseFlags = kDefaultParseFlags		// with parseFlags = kDefaultParseFlags
template <typename InputStream, typename Handler>		template <typename InputStream, typename Handler>
bool Parse(InputStream& is, Handler& handler);		bool Parse(InputStream& is, Handler& handler);
skipping to change at line 246		skipping to change at line 247
Anyway, using `Writer` API is even simpler than generating a JSON by ad hoc meth ods.		Anyway, using `Writer` API is even simpler than generating a JSON by ad hoc meth ods.
## Template {#WriterTemplate}		## Template {#WriterTemplate}
`Writer` has a minor design difference to `Reader`. `Writer` is a template class , not a typedef. There is no `GenericWriter`. The following is the declaration.		`Writer` has a minor design difference to `Reader`. `Writer` is a template class , not a typedef. There is no `GenericWriter`. The following is the declaration.
~~~~~~~~~~cpp		~~~~~~~~~~cpp
namespace rapidjson {		namespace rapidjson {
template<typename OutputStream, typename SourceEncoding = UTF8<>, typename Targe tEncoding = UTF8<>, typename Allocator = CrtAllocator<> >		template<typename OutputStream, typename SourceEncoding = UTF8<>, typename Targe tEncoding = UTF8<>, typename Allocator = CrtAllocator<>, unsigned writeFlags = k WriteDefaultFlags>
class Writer {		class Writer {
public:		public:
Writer(OutputStream& os, Allocator* allocator = 0, size_t levelDepth = kDefa ultLevelDepth)		Writer(OutputStream& os, Allocator* allocator = 0, size_t levelDepth = kDefa ultLevelDepth)
// ...		// ...
};		};
} // namespace rapidjson		} // namespace rapidjson
~~~~~~~~~~		~~~~~~~~~~
The `OutputStream` template parameter is the type of output stream. It cannot be deduced and must be specified by user.		The `OutputStream` template parameter is the type of output stream. It cannot be deduced and must be specified by user.
The `SourceEncoding` template parameter specifies the encoding to be used in `St ring(const Ch*, ...)`.		The `SourceEncoding` template parameter specifies the encoding to be used in `St ring(const Ch*, ...)`.
The `TargetEncoding` template parameter specifies the encoding in the output str eam.		The `TargetEncoding` template parameter specifies the encoding in the output str eam.
The last one, `Allocator` is the type of allocator, which is used for allocating		The `Allocator` is the type of allocator, which is used for allocating internal
internal data structure (a stack).		data structure (a stack).
		The `writeFlags` are combination of the following bit-flags:
		Parse flags | Meaning
		------------------------------|-----------------------------------
		`kWriteNoFlags` | No flag is set.
		`kWriteDefaultFlags` | Default write flags. It is equal to macro `RAPID
		JSON_WRITE_DEFAULT_FLAGS`, which is defined as `kWriteNoFlags`.
		`kWriteValidateEncodingFlag` | Validate encoding of JSON strings.
		`kWriteNanAndInfFlag` | Allow writing of `Infinity`, `-Infinity` and `Na
		N`.
Besides, the constructor of `Writer` has a `levelDepth` parameter. This paramete r affects the initial memory allocated for storing information per hierarchy lev el.		Besides, the constructor of `Writer` has a `levelDepth` parameter. This paramete r affects the initial memory allocated for storing information per hierarchy lev el.
## PrettyWriter {#PrettyWriter}		## PrettyWriter {#PrettyWriter}
While the output of `Writer` is the most condensed JSON without white-spaces, su itable for network transfer or storage, it is not easily readable by human.		While the output of `Writer` is the most condensed JSON without white-spaces, su itable for network transfer or storage, it is not easily readable by human.
Therefore, RapidJSON provides a `PrettyWriter`, which adds indentation and line feeds in the output.		Therefore, RapidJSON provides a `PrettyWriter`, which adds indentation and line feeds in the output.
The usage of `PrettyWriter` is exactly the same as `Writer`, expect that `Pretty Writer` provides a `SetIndent(Ch indentChar, unsigned indentCharCount)` function . The default is 4 spaces.		The usage of `PrettyWriter` is exactly the same as `Writer`, expect that `Pretty Writer` provides a `SetIndent(Ch indentChar, unsigned indentCharCount)` function . The default is 4 spaces.
## Completeness and Reset {#CompletenessReset}		## Completeness and Reset {#CompletenessReset}
A `Writer` can only output a single JSON, which can be any JSON type at the root . Once the singular event for root (e.g. `String()`), or the last matching `EndO bject()` or `EndArray()` event, is handled, the output JSON is well-formed and c omplete. User can detect this state by calling `Writer::IsComplete()`.		A `Writer` can only output a single JSON, which can be any JSON type at the root . Once the singular event for root (e.g. `String()`), or the last matching `EndO bject()` or `EndArray()` event, is handled, the output JSON is well-formed and c omplete. User can detect this state by calling `Writer::IsComplete()`.
When a JSON is complete, the `Writer` cannot accept any new events. Otherwise th e output will be invalid (i.e. having more than one root). To reuse the `Writer` object, user can call `Writer::Reset(OutputStream& os)` to reset all internal s tates of the `Writer` with a new output stream.		When a JSON is complete, the `Writer` cannot accept any new events. Otherwise th e output will be invalid (i.e. having more than one root). To reuse the `Writer` object, user can call `Writer::Reset(OutputStream& os)` to reset all internal s tates of the `Writer` with a new output stream.
# Techniques {#Techniques}		# Techniques {#SaxTechniques}
## Parsing JSON to Custom Data Structure {#CustomDataStructure}		## Parsing JSON to Custom Data Structure {#CustomDataStructure}
`Document`'s parsing capability is completely based on `Reader`. Actually `Docum ent` is a handler which receives events from a reader to build a DOM during pars ing.		`Document`'s parsing capability is completely based on `Reader`. Actually `Docum ent` is a handler which receives events from a reader to build a DOM during pars ing.
User may uses `Reader` to build other data structures directly. This eliminates building of DOM, thus reducing memory and improving performance.		User may uses `Reader` to build other data structures directly. This eliminates building of DOM, thus reducing memory and improving performance.
In the following `messagereader` example, `ParseMessages()` parses a JSON which should be an object with key-string pairs.		In the following `messagereader` example, `ParseMessages()` parses a JSON which should be an object with key-string pairs.
~~~~~~~~~~cpp		~~~~~~~~~~cpp
skipping to change at line 422		skipping to change at line 432
CapitalizeFilter(OutputHandler& out) : out_(out), buffer_() {		CapitalizeFilter(OutputHandler& out) : out_(out), buffer_() {
}		}
bool Null() { return out_.Null(); }		bool Null() { return out_.Null(); }
bool Bool(bool b) { return out_.Bool(b); }		bool Bool(bool b) { return out_.Bool(b); }
bool Int(int i) { return out_.Int(i); }		bool Int(int i) { return out_.Int(i); }
bool Uint(unsigned u) { return out_.Uint(u); }		bool Uint(unsigned u) { return out_.Uint(u); }
bool Int64(int64_t i) { return out_.Int64(i); }		bool Int64(int64_t i) { return out_.Int64(i); }
bool Uint64(uint64_t u) { return out_.Uint64(u); }		bool Uint64(uint64_t u) { return out_.Uint64(u); }
bool Double(double d) { return out_.Double(d); }		bool Double(double d) { return out_.Double(d); }
		bool RawNumber(const char* str, SizeType length, bool copy) { return out_.Ra wNumber(str, length, copy); }
bool String(const char* str, SizeType length, bool) {		bool String(const char* str, SizeType length, bool) {
buffer_.clear();		buffer_.clear();
for (SizeType i = 0; i < length; i++)		for (SizeType i = 0; i < length; i++)
buffer_.push_back(std::toupper(str[i]));		buffer_.push_back(std::toupper(str[i]));
return out_.String(&buffer_.front(), length, true); // true = output han dler need to copy the string		return out_.String(&buffer_.front(), length, true); // true = output han dler need to copy the string
}		}
bool StartObject() { return out_.StartObject(); }		bool StartObject() { return out_.StartObject(); }
bool Key(const char* str, SizeType length, bool copy) { return String(str, l ength, copy); }		bool Key(const char* str, SizeType length, bool copy) { return String(str, l ength, copy); }
bool EndObject(SizeType memberCount) { return out_.EndObject(memberCount); }		bool EndObject(SizeType memberCount) { return out_.EndObject(memberCount); }
bool StartArray() { return out_.StartArray(); }		bool StartArray() { return out_.StartArray(); }
End of changes. 8 change blocks.
7 lines changed or deleted		20 lines changed or added

---