gvsafronov/rapidjson
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Update Stream.md

Browse Source
This commit is contained in:
Milo Yip 2016-02-08 00:49:00 +08:00
parent 562549fbac
commit 0f7cb315ef
2 changed files with 128 additions and 24 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

78
doc/stream.md
View File

@ -119,6 +119,58 @@ fclose(fp);
It can also directs the output to `stdout`.
# iostream Wrapper {#iostreamWrapper}
Due to users' requests, RapidJSON provided official wrappers for `std::basic_istream` and `std::basic_ostream`. However, please note that the performance will be much lower than the other streams above.
## IStreamWrapper {#IStreamWrapper}
`IStreamWrapper` wraps any class drived from `std::istream`, such as `std::istringstream`, `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`, into 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 do not contain JSON itself, but they wrap byte streams to provide basic encoding/decoding function.
@ -277,14 +329,14 @@ There are two special interface, `PutBegin()` and `PutEnd()`, which are only for
## Example: istream wrapper {#ExampleIStreamWrapper}
The following example is a wrapper of `std::istream`, which only implements 3 functions.
The following example is a simple wrapper of `std::istream`, which only implements 3 functions.
~~~~~~~~~~cpp
class IStreamWrapper {
class MyIStreamWrapper {
public:
typedef char Ch;
IStreamWrapper(std::istream& is) : is_(is) {
MyIStreamWrapper(std::istream& is) : is_(is) {
}
Ch Peek() const { // 1
@ -305,8 +357,8 @@ public:
size_t PutEnd(Ch*) { assert(false); return 0; }
private:
IStreamWrapper(const IStreamWrapper&);
IStreamWrapper& operator=(const IStreamWrapper&);
MyIStreamWrapper(const MyIStreamWrapper&);
MyIStreamWrapper& operator=(const MyIStreamWrapper&);
std::istream& is_;
};
@ -317,7 +369,7 @@ User can use it to wrap instances of `std::stringstream`, `std::ifstream`.
~~~~~~~~~~cpp
const char* json = "[1,2,3,4]";
std::stringstream ss(json);
IStreamWrapper is(ss);
MyIStreamWrapper is(ss);
Document d;
d.ParseStream(is);
@ -327,14 +379,14 @@ Note that, this implementation may not be as efficient as RapidJSON's memory or
## Example: ostream wrapper {#ExampleOStreamWrapper}
The following example is a wrapper of `std::istream`, which only implements 2 functions.
The following example is a simple wrapper of `std::istream`, which only implements 2 functions.
~~~~~~~~~~cpp
class OStreamWrapper {
class MyOStreamWrapper {
public:
typedef char Ch;
OStreamWrapper(std::ostream& os) : os_(os) {
MyOStreamWrapper(std::ostream& os) : os_(os) {
}
Ch Peek() const { assert(false); return '\0'; }
@ -347,8 +399,8 @@ public:
size_t PutEnd(Ch*) { assert(false); return 0; }
private:
OStreamWrapper(const OStreamWrapper&);
OStreamWrapper& operator=(const OStreamWrapper&);
MyOStreamWrapper(const MyOStreamWrapper&);
MyOStreamWrapper& operator=(const MyOStreamWrapper&);
std::ostream& os_;
};
@ -361,9 +413,9 @@ Document d;
// ...
std::stringstream ss;
OSStreamWrapper os(ss);
MyOStreamWrapper os(ss);
Writer<OStreamWrapper> writer(os);
Writer<MyOStreamWrapper> writer(os);
d.Accept(writer);
~~~~~~~~~~

74
doc/stream.zh-cn.md
View File

@ -119,6 +119,58 @@ fclose(fp);
它也可以把输出导向`stdout`。
# iostream 包装类 {#iostreamWrapper}
基于用户的要求，RapidJSON提供了正式的 `std::basic_istream` 和 `std::basic_ostream` 包装类。然而，请注意其性能会大大低于以上的其他流。
## IStreamWrapper {#IStreamWrapper}
`IStreamWrapper` 把任何继承自 `std::istream` 的类（如 `std::istringstream`、`std::stringstream`、`std::ifstream`、`std::fstream`）包装成 RapidJSON 的输入流。
~~~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);
~~~
对于继承自 `std::wistream` 的类，则使用 `WIStreamWrapper`。
## OStreamWrapper {#OStreamWrapper}
相似地，`OStreamWrapper` 把任何继承自 `std::ostream` 的类（如 `std::ostringstream`、`std::stringstream`、`std::ofstream`、`std::fstream`）包装成 RapidJSON 的输出流。
~~~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);
~~~
对于继承自 `std::wistream` 的类，则使用 `WIStreamWrapper`。
# 编码流 {#EncodedStreams}
编码流（encoded streams）本身不存储JSON，它们是通过包装字节流来提供基本的编码／解码功能。
@ -277,14 +329,14 @@ concept Stream {
## 例子：istream的包装类 {#ExampleIStreamWrapper}
以下的例子是`std::istream`的包装类，它只需现3个函数。
以下的简单例子是`std::istream`的包装类，它只需现3个函数。
~~~~~~~~~~cpp
class IStreamWrapper {
class MyIStreamWrapper {
public:
typedef char Ch;
IStreamWrapper(std::istream& is) : is_(is) {
MyIStreamWrapper(std::istream& is) : is_(is) {
}
Ch Peek() const { // 1
@ -305,8 +357,8 @@ public:
size_t PutEnd(Ch*) { assert(false); return 0; }
private:
IStreamWrapper(const IStreamWrapper&);
IStreamWrapper& operator=(const IStreamWrapper&);
MyIStreamWrapper(const MyIStreamWrapper&);
MyIStreamWrapper& operator=(const MyIStreamWrapper&);
std::istream& is_;
};
@ -317,7 +369,7 @@ private:
~~~~~~~~~~cpp
const char* json = "[1,2,3,4]";
std::stringstream ss(json);
IStreamWrapper is(ss);
MyIStreamWrapper is(ss);
Document d;
d.ParseStream(is);
@ -330,7 +382,7 @@ d.ParseStream(is);
以下的例子是`std::istream`的包装类，它只需实现2个函数。
~~~~~~~~~~cpp
class OStreamWrapper {
class MyOStreamWrapper {
public:
typedef char Ch;
@ -347,8 +399,8 @@ public:
size_t PutEnd(Ch*) { assert(false); return 0; }
private:
OStreamWrapper(const OStreamWrapper&);
OStreamWrapper& operator=(const OStreamWrapper&);
MyOStreamWrapper(const MyOStreamWrapper&);
MyOStreamWrapper& operator=(const MyOStreamWrapper&);
std::ostream& os_;
};
@ -361,9 +413,9 @@ Document d;
// ...
std::stringstream ss;
OSStreamWrapper os(ss);
MyOStreamWrapper os(ss);
Writer<OStreamWrapper> writer(os);
Writer<MyOStreamWrapper> writer(os);
d.Accept(writer);
~~~~~~~~~~