"Fossies" - the Fresh Open Source Software Archive  

Source code changes of the file "doc/stream.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.

stream.md  (rapidjson-1.0.2)	:	stream.md  (rapidjson-1.1.0)
skipping to change at line 122		skipping to change at line 122
FileWriteStream os(fp, writeBuffer, sizeof(writeBuffer));		FileWriteStream os(fp, writeBuffer, sizeof(writeBuffer));
Writer<FileWriteStream> writer(os);		Writer<FileWriteStream> writer(os);
d.Accept(writer);		d.Accept(writer);
fclose(fp);		fclose(fp);
~~~~~~~~~~		~~~~~~~~~~
It can also directs the output to `stdout`.		It can also directs the output to `stdout`.
		# iostream Wrapper {#iostreamWrapper}
		Due to users' requests, RapidJSON provided official wrappers for `std::basic_ist
		ream` and `std::basic_ostream`. However, please note that the performance will b
		e much lower than the other streams above.
		## IStreamWrapper {#IStreamWrapper}
		`IStreamWrapper` wraps any class drived from `std::istream`, such as `std::istri
		ngstream`, `std::stringstream`, `std::ifstream`, `std::fstream`, into RapidJSON'
		s input stream.
		~~~cpp
		#include <rapidjson/document.h>
		#include <rapidjson/istreamwrapper.h>
		#include <fstream>
		using namespace rapidjson;
		using namespace std;
		ifstream ifs("test.json");
		IStreamWrapper isw(ifs);
		Document d;
		d.ParseStream(isw);
		~~~
		For classes derived from `std::wistream`, use `WIStreamWrapper`.
		## OStreamWrapper {#OStreamWrapper}
		Similarly, `OStreamWrapper` wraps any class derived from `std::ostream`, such as
		`std::ostringstream`, `std::stringstream`, `std::ofstream`, `std::fstream`, int
		o RapidJSON's input stream.
		~~~cpp
		#include <rapidjson/document.h>
		#include <rapidjson/ostreamwrapper.h>
		#include <rapidjson/writer.h>
		#include <fstream>
		using namespace rapidjson;
		using namespace std;
		Document d;
		d.Parse(json);
		// ...
		ofstream ofs("output.json");
		OStreamWrapper osw(ofs);
		Writer<OStreamWrapper> writer(osw);
		d.Accept(writer);
		~~~
		For classes derived from `std::wostream`, use `WOStreamWrapper`.
# Encoded Streams {#EncodedStreams}		# Encoded Streams {#EncodedStreams}
Encoded streams do not contain JSON itself, but they wrap byte streams to provid e basic encoding/decoding function.		Encoded streams do not contain JSON itself, but they wrap byte streams to provid e basic encoding/decoding function.
As mentioned above, UTF-8 byte streams can be read directly. However, UTF-16 and UTF-32 have endian issue. To handle endian correctly, it needs to convert bytes into characters (e.g. `wchar_t` for UTF-16) while reading, and characters into bytes while writing.		As mentioned above, UTF-8 byte streams can be read directly. However, UTF-16 and UTF-32 have endian issue. To handle endian correctly, it needs to convert bytes into characters (e.g. `wchar_t` for UTF-16) while reading, and characters into bytes while writing.
Besides, it also need to handle [byte order mark (BOM)](http://en.wikipedia.org/ wiki/Byte_order_mark). When reading from a byte stream, it is needed to detect o r just consume the BOM if exists. When writing to a byte stream, it can optional ly write BOM.		Besides, it also need to handle [byte order mark (BOM)](http://en.wikipedia.org/ wiki/Byte_order_mark). When reading from a byte stream, it is needed to detect o r just consume the BOM if exists. When writing to a byte stream, it can optional ly write BOM.
If the encoding of stream is known in compile-time, you may use `EncodedInputStr eam` and `EncodedOutputStream`. If the stream can be UTF-8, UTF-16LE, UTF-16BE, UTF-32LE, UTF-32BE JSON, and it is only known in runtime, you may use `AutoUTFIn putStream` and `AutoUTFOutputStream`. These streams are defined in `rapidjson/en codedstream.h`.		If the encoding of stream is known in compile-time, you may use `EncodedInputStr eam` and `EncodedOutputStream`. If the stream can be UTF-8, UTF-16LE, UTF-16BE, UTF-32LE, UTF-32BE JSON, and it is only known in runtime, you may use `AutoUTFIn putStream` and `AutoUTFOutputStream`. These streams are defined in `rapidjson/en codedstream.h`.
skipping to change at line 280		skipping to change at line 332
size_t PutEnd(Ch* begin);		size_t PutEnd(Ch* begin);
}		}
~~~~~~~~~~		~~~~~~~~~~
For input stream, they must implement `Peek()`, `Take()` and `Tell()`.		For input stream, they must implement `Peek()`, `Take()` and `Tell()`.
For output stream, they must implement `Put()` and `Flush()`.		For output stream, they must implement `Put()` and `Flush()`.
There are two special interface, `PutBegin()` and `PutEnd()`, which are only for *in situ* parsing. Normal streams do not implement them. However, if the interf ace is not needed for a particular stream, it is still need to a dummy implement ation, otherwise will generate compilation error.		There are two special interface, `PutBegin()` and `PutEnd()`, which are only for *in situ* parsing. Normal streams do not implement them. However, if the interf ace is not needed for a particular stream, it is still need to a dummy implement ation, otherwise will generate compilation error.
## Example: istream wrapper {#ExampleIStreamWrapper}		## Example: istream wrapper {#ExampleIStreamWrapper}
The following example is a wrapper of `std::istream`, which only implements 3 fu nctions.		The following example is a simple wrapper of `std::istream`, which only implemen ts 3 functions.
~~~~~~~~~~cpp		~~~~~~~~~~cpp
class IStreamWrapper {		class MyIStreamWrapper {
public:		public:
typedef char Ch;		typedef char Ch;
IStreamWrapper(std::istream& is) : is_(is) {		MyIStreamWrapper(std::istream& is) : is_(is) {
}		}
Ch Peek() const { // 1		Ch Peek() const { // 1
int c = is_.peek();		int c = is_.peek();
return c == std::char_traits<char>::eof() ? '\0' : (Ch)c;		return c == std::char_traits<char>::eof() ? '\0' : (Ch)c;
}		}
Ch Take() { // 2		Ch Take() { // 2
int c = is_.get();		int c = is_.get();
return c == std::char_traits<char>::eof() ? '\0' : (Ch)c;		return c == std::char_traits<char>::eof() ? '\0' : (Ch)c;
}		}
size_t Tell() const { return (size_t)is_.tellg(); } // 3		size_t Tell() const { return (size_t)is_.tellg(); } // 3
Ch* PutBegin() { assert(false); return 0; }		Ch* PutBegin() { assert(false); return 0; }
void Put(Ch) { assert(false); }		void Put(Ch) { assert(false); }
void Flush() { assert(false); }		void Flush() { assert(false); }
size_t PutEnd(Ch*) { assert(false); return 0; }		size_t PutEnd(Ch*) { assert(false); return 0; }
private:		private:
IStreamWrapper(const IStreamWrapper&);		MyIStreamWrapper(const MyIStreamWrapper&);
IStreamWrapper& operator=(const IStreamWrapper&);		MyIStreamWrapper& operator=(const MyIStreamWrapper&);
std::istream& is_;		std::istream& is_;
};		};
~~~~~~~~~~		~~~~~~~~~~
User can use it to wrap instances of `std::stringstream`, `std::ifstream`.		User can use it to wrap instances of `std::stringstream`, `std::ifstream`.
~~~~~~~~~~cpp		~~~~~~~~~~cpp
const char* json = "[1,2,3,4]";		const char* json = "[1,2,3,4]";
std::stringstream ss(json);		std::stringstream ss(json);
IStreamWrapper is(ss);		MyIStreamWrapper is(ss);
Document d;		Document d;
d.Parse(is);		d.ParseStream(is);
~~~~~~~~~~		~~~~~~~~~~
Note that, this implementation may not be as efficient as RapidJSON's memory or file streams, due to internal overheads of the standard library.		Note that, this implementation may not be as efficient as RapidJSON's memory or file streams, due to internal overheads of the standard library.
## Example: ostream wrapper {#ExampleOStreamWrapper}		## Example: ostream wrapper {#ExampleOStreamWrapper}
The following example is a wrapper of `std::istream`, which only implements 2 fu nctions.		The following example is a simple wrapper of `std::istream`, which only implemen ts 2 functions.
~~~~~~~~~~cpp		~~~~~~~~~~cpp
class OStreamWrapper {		class MyOStreamWrapper {
public:		public:
typedef char Ch;		typedef char Ch;
OStreamWrapper(std::ostream& os) : os_(os) {		MyOStreamWrapper(std::ostream& os) : os_(os) {
}		}
Ch Peek() const { assert(false); return '\0'; }		Ch Peek() const { assert(false); return '\0'; }
Ch Take() { assert(false); return '\0'; }		Ch Take() { assert(false); return '\0'; }
size_t Tell() const { }		size_t Tell() const { }
Ch* PutBegin() { assert(false); return 0; }		Ch* PutBegin() { assert(false); return 0; }
void Put(Ch c) { os_.put(c); } // 1		void Put(Ch c) { os_.put(c); } // 1
void Flush() { os_.flush(); } // 2		void Flush() { os_.flush(); } // 2
size_t PutEnd(Ch*) { assert(false); return 0; }		size_t PutEnd(Ch*) { assert(false); return 0; }
private:		private:
OStreamWrapper(const OStreamWrapper&);		MyOStreamWrapper(const MyOStreamWrapper&);
OStreamWrapper& operator=(const OStreamWrapper&);		MyOStreamWrapper& operator=(const MyOStreamWrapper&);
std::ostream& os_;		std::ostream& os_;
};		};
~~~~~~~~~~		~~~~~~~~~~
User can use it to wrap instances of `std::stringstream`, `std::ofstream`.		User can use it to wrap instances of `std::stringstream`, `std::ofstream`.
~~~~~~~~~~cpp		~~~~~~~~~~cpp
Document d;		Document d;
// ...		// ...
std::stringstream ss;		std::stringstream ss;
OSStreamWrapper os(ss);		MyOStreamWrapper os(ss);
Writer<OStreamWrapper> writer(os);		Writer<MyOStreamWrapper> writer(os);
d.Accept(writer);		d.Accept(writer);
~~~~~~~~~~		~~~~~~~~~~
Note that, this implementation may not be as efficient as RapidJSON's memory or file streams, due to internal overheads of the standard library.		Note that, this implementation may not be as efficient as RapidJSON's memory or file streams, due to internal overheads of the standard library.
# Summary {#Summary}		# Summary {#Summary}
This section describes stream classes available in RapidJSON. Memory streams are simple. File stream can reduce the memory required during JSON parsing and gene ration, if the JSON is stored in file system. Encoded streams converts between b yte streams and character streams. Finally, user may create custom streams using a simple interface.		This section describes stream classes available in RapidJSON. Memory streams are simple. File stream can reduce the memory required during JSON parsing and gene ration, if the JSON is stored in file system. Encoded streams converts between b yte streams and character streams. Finally, user may create custom streams using a simple interface.
End of changes. 13 change blocks.
14 lines changed or deleted		72 lines changed or added

---