Debian Codegraph @

LspCpp/third_party/rapidjson/doc/stream.zh-cn.md

raw
1 # 流
2
3 在 RapidJSON 中,`rapidjson::Stream` 是用於读写 JSON 的概念(概念是指 C++ 的 concept)。在这里我们先介绍如何使用 RapidJSON 提供的各种流。然后再看看如何自行定义流。
4
5 [TOC]
6
7 # 内存流 {#MemoryStreams}
8
9 内存流把 JSON 存储在内存之中。
10
11 ## StringStream(输入){#StringStream}
12
13 `StringStream` 是最基本的输入流,它表示一个完整的、只读的、存储于内存的 JSON。它在 `rapidjson/rapidjson.h` 中定义。
14
15 ~~~~~~~~~~cpp
16 #include "rapidjson/document.h" // 会包含 "rapidjson/rapidjson.h"
17
18 using namespace rapidjson;
19
20 // ...
21 const char json[] = "[1, 2, 3, 4]";
22 StringStream s(json);
23
24 Document d;
25 d.ParseStream(s);
26 ~~~~~~~~~~
27
28 由于这是非常常用的用法,RapidJSON 提供 `Document::Parse(const char*)` 去做完全相同的事情:
29
30 ~~~~~~~~~~cpp
31 // ...
32 const char json[] = "[1, 2, 3, 4]";
33 Document d;
34 d.Parse(json);
35 ~~~~~~~~~~
36
37 需要注意,`StringStream` 是 `GenericStringStream<UTF8<> >` 的 typedef,使用者可用其他编码类去代表流所使用的字符集。
38
39 ## StringBuffer(输出){#StringBuffer}
40
41 `StringBuffer` 是一个简单的输出流。它分配一个内存缓冲区,供写入整个 JSON。可使用 `GetString()` 来获取该缓冲区。
42
43 ~~~~~~~~~~cpp
44 #include "rapidjson/stringbuffer.h"
45 #include <rapidjson/writer.h>
46
47 StringBuffer buffer;
48 Writer<StringBuffer> writer(buffer);
49 d.Accept(writer);
50
51 const char* output = buffer.GetString();
52 ~~~~~~~~~~
53
54 当缓冲区满溢,它将自动增加容量。缺省容量是 256 个字符(UTF8 是 256 字节,UTF16 是 512 字节等)。使用者能自行提供分配器及初始容量。
55
56 ~~~~~~~~~~cpp
57 StringBuffer buffer1(0, 1024); // 使用它的分配器,初始大小 = 1024
58 StringBuffer buffer2(allocator, 1024);
59 ~~~~~~~~~~
60
61 如无设置分配器,`StringBuffer` 会自行实例化一个内部分配器。
62
63 相似地,`StringBuffer` 是 `GenericStringBuffer<UTF8<> >` 的 typedef。
64
65 # 文件流 {#FileStreams}
66
67 当要从文件解析一个 JSON,你可以把整个 JSON 读入内存并使用上述的 `StringStream`。
68
69 然而,若 JSON 很大,或是内存有限,你可以改用 `FileReadStream`。它只会从文件读取一部分至缓冲区,然后让那部分被解析。若缓冲区的字符都被读完,它会再从文件读取下一部分。
70
71 ## FileReadStream(输入) {#FileReadStream}
72
73 `FileReadStream` 通过 `FILE` 指针读取文件。使用者需要提供一个缓冲区。
74
75 ~~~~~~~~~~cpp
76 #include "rapidjson/filereadstream.h"
77 #include <cstdio>
78
79 using namespace rapidjson;
80
81 FILE* fp = fopen("big.json", "rb"); // 非 Windows 平台使用 "r"
82
83 char readBuffer[65536];
84 FileReadStream is(fp, readBuffer, sizeof(readBuffer));
85
86 Document d;
87 d.ParseStream(is);
88
89 fclose(fp);
90 ~~~~~~~~~~
91
92 与 `StringStreams` 不一样,`FileReadStream` 是一个字节流。它不处理编码。若文件并非 UTF-8 编码,可以把字节流用 `EncodedInputStream` 包装。我们很快会讨论这个问题。
93
94 除了读取文件,使用者也可以使用 `FileReadStream` 来读取 `stdin`。
95
96 ## FileWriteStream(输出){#FileWriteStream}
97
98 `FileWriteStream` 是一个含缓冲功能的输出流。它的用法与 `FileReadStream` 非常相似。
99
100 ~~~~~~~~~~cpp
101 #include "rapidjson/filewritestream.h"
102 #include <rapidjson/writer.h>
103 #include <cstdio>
104
105 using namespace rapidjson;
106
107 Document d;
108 d.Parse(json);
109 // ...
110
111 FILE* fp = fopen("output.json", "wb"); // 非 Windows 平台使用 "w"
112
113 char writeBuffer[65536];
114 FileWriteStream os(fp, writeBuffer, sizeof(writeBuffer));
115
116 Writer<FileWriteStream> writer(os);
117 d.Accept(writer);
118
119 fclose(fp);
120 ~~~~~~~~~~
121
122 它也可以把输出导向 `stdout`。
123
124 # iostream 包装类 {#iostreamWrapper}
125
126 基于用户的要求,RapidJSON 提供了正式的 `std::basic_istream` 和 `std::basic_ostream` 包装类。然而,请注意其性能会大大低于以上的其他流。
127
128 ## IStreamWrapper {#IStreamWrapper}
129
130 `IStreamWrapper` 把任何继承自 `std::istream` 的类(如 `std::istringstream`、`std::stringstream`、`std::ifstream`、`std::fstream`)包装成 RapidJSON 的输入流。
131
132 ~~~cpp
133 #include <rapidjson/document.h>
134 #include <rapidjson/istreamwrapper.h>
135 #include <fstream>
136
137 using namespace rapidjson;
138 using namespace std;
139
140 ifstream ifs("test.json");
141 IStreamWrapper isw(ifs);
142
143 Document d;
144 d.ParseStream(isw);
145 ~~~
146
147 对于继承自 `std::wistream` 的类,则使用 `WIStreamWrapper`。
148
149 ## OStreamWrapper {#OStreamWrapper}
150
151 相似地,`OStreamWrapper` 把任何继承自 `std::ostream` 的类(如 `std::ostringstream`、`std::stringstream`、`std::ofstream`、`std::fstream`)包装成 RapidJSON 的输出流。
152
153 ~~~cpp
154 #include <rapidjson/document.h>
155 #include <rapidjson/ostreamwrapper.h>
156 #include <rapidjson/writer.h>
157 #include <fstream>
158
159 using namespace rapidjson;
160 using namespace std;
161
162 Document d;
163 d.Parse(json);
164
165 // ...
166
167 ofstream ofs("output.json");
168 OStreamWrapper osw(ofs);
169
170 Writer<OStreamWrapper> writer(osw);
171 d.Accept(writer);
172 ~~~
173
174 对于继承自 `std::wistream` 的类,则使用 `WIStreamWrapper`。
175
176 # 编码流 {#EncodedStreams}
177
178 编码流(encoded streams)本身不存储 JSON,它们是通过包装字节流来提供基本的编码/解码功能。
179
180 如上所述,我们可以直接读入 UTF-8 字节流。然而,UTF-16 及 UTF-32 有字节序(endian)问题。要正确地处理字节序,需要在读取时把字节转换成字符(如对 UTF-16 使用 `wchar_t`),以及在写入时把字符转换为字节。
181
182 除此以外,我们也需要处理 [字节顺序标记(byte order mark, BOM)](http://en.wikipedia.org/wiki/Byte_order_mark)。当从一个字节流读取时,需要检测 BOM,或者仅仅是把存在的 BOM 消去。当把 JSON 写入字节流时,也可选择写入 BOM。
183
184 若一个流的编码在编译期已知,你可使用 `EncodedInputStream` 及 `EncodedOutputStream`。若一个流可能存储 UTF-8、UTF-16LE、UTF-16BE、UTF-32LE、UTF-32BE 的 JSON,并且编码只能在运行时得知,你便可以使用 `AutoUTFInputStream` 及 `AutoUTFOutputStream`。这些流定义在 `rapidjson/encodedstream.h`。
185
186 注意到,这些编码流可以施于文件以外的流。例如,你可以用编码流包装内存中的文件或自定义的字节流。
187
188 ## EncodedInputStream {#EncodedInputStream}
189
190 `EncodedInputStream` 含两个模板参数。第一个是 `Encoding` 类型,例如定义于 `rapidjson/encodings.h` 的 `UTF8`、`UTF16LE`。第二个参数是被包装的流的类型。
191
192 ~~~~~~~~~~cpp
193 #include "rapidjson/document.h"
194 #include "rapidjson/filereadstream.h" // FileReadStream
195 #include "rapidjson/encodedstream.h" // EncodedInputStream
196 #include <cstdio>
197
198 using namespace rapidjson;
199
200 FILE* fp = fopen("utf16le.json", "rb"); // 非 Windows 平台使用 "r"
201
202 char readBuffer[256];
203 FileReadStream bis(fp, readBuffer, sizeof(readBuffer));
204
205 EncodedInputStream<UTF16LE<>, FileReadStream> eis(bis); // 用 eis 包装 bis
206
207 Document d; // Document 为 GenericDocument<UTF8<> >
208 d.ParseStream<0, UTF16LE<> >(eis); // 把 UTF-16LE 文件解析至内存中的 UTF-8
209
210 fclose(fp);
211 ~~~~~~~~~~
212
213 ## EncodedOutputStream {#EncodedOutputStream}
214
215 `EncodedOutputStream` 也是相似的,但它的构造函数有一个 `bool putBOM` 参数,用于控制是否在输出字节流写入 BOM。
216
217 ~~~~~~~~~~cpp
218 #include "rapidjson/filewritestream.h" // FileWriteStream
219 #include "rapidjson/encodedstream.h" // EncodedOutputStream
220 #include <rapidjson/writer.h>
221 #include <cstdio>
222
223 Document d; // Document 为 GenericDocument<UTF8<> >
224 // ...
225
226 FILE* fp = fopen("output_utf32le.json", "wb"); // 非 Windows 平台使用 "w"
227
228 char writeBuffer[256];
229 FileWriteStream bos(fp, writeBuffer, sizeof(writeBuffer));
230
231 typedef EncodedOutputStream<UTF32LE<>, FileWriteStream> OutputStream;
232 OutputStream eos(bos, true); // 写入 BOM
233
234 Writer<OutputStream, UTF8<>, UTF32LE<>> writer(eos);
235 d.Accept(writer); // 这里从内存的 UTF-8 生成 UTF32-LE 文件
236
237 fclose(fp);
238 ~~~~~~~~~~
239
240 ## AutoUTFInputStream {#AutoUTFInputStream}
241
242 有时候,应用软件可能需要㲃理所有可支持的 JSON 编码。`AutoUTFInputStream` 会先使用 BOM 来检测编码。若 BOM 不存在,它便会使用合法 JSON 的特性来检测。若两种方法都失败,它就会倒退至构造函数提供的 UTF 类型。
243
244 由于字符(编码单元/code unit)可能是 8 位、16 位或 32 位,`AutoUTFInputStream` 需要一个能至少储存 32 位的字符类型。我们可以使用 `unsigned` 作为模板参数:
245
246 ~~~~~~~~~~cpp
247 #include "rapidjson/document.h"
248 #include "rapidjson/filereadstream.h" // FileReadStream
249 #include "rapidjson/encodedstream.h" // AutoUTFInputStream
250 #include <cstdio>
251
252 using namespace rapidjson;
253
254 FILE* fp = fopen("any.json", "rb"); // 非 Windows 平台使用 "r"
255
256 char readBuffer[256];
257 FileReadStream bis(fp, readBuffer, sizeof(readBuffer));
258
259 AutoUTFInputStream<unsigned, FileReadStream> eis(bis); // 用 eis 包装 bis
260
261 Document d; // Document 为 GenericDocument<UTF8<> >
262 d.ParseStream<0, AutoUTF<unsigned> >(eis); // 把任何 UTF 编码的文件解析至内存中的 UTF-8
263
264 fclose(fp);
265 ~~~~~~~~~~
266
267 当要指定流的编码,可使用上面例子中 `ParseStream()` 的参数 `AutoUTF<CharType>`。
268
269 你可以使用 `UTFType GetType()` 去获取 UTF 类型,并且用 `HasBOM()` 检测输入流是否含有 BOM。
270
271 ## AutoUTFOutputStream {#AutoUTFOutputStream}
272
273 相似地,要在运行时选择输出的编码,我们可使用 `AutoUTFOutputStream`。这个类本身并非「自动」。你需要在运行时指定 UTF 类型,以及是否写入 BOM。
274
275 ~~~~~~~~~~cpp
276 using namespace rapidjson;
277
278 void WriteJSONFile(FILE* fp, UTFType type, bool putBOM, const Document& d) {
279 char writeBuffer[256];
280 FileWriteStream bos(fp, writeBuffer, sizeof(writeBuffer));
281
282 typedef AutoUTFOutputStream<unsigned, FileWriteStream> OutputStream;
283 OutputStream eos(bos, type, putBOM);
284
285 Writer<OutputStream, UTF8<>, AutoUTF<> > writer;
286 d.Accept(writer);
287 }
288 ~~~~~~~~~~
289
290 `AutoUTFInputStream`/`AutoUTFOutputStream` 是比 `EncodedInputStream`/`EncodedOutputStream` 方便。但前者会产生一点运行期额外开销。
291
292 # 自定义流 {#CustomStream}
293
294 除了内存/文件流,使用者可创建自行定义适配 RapidJSON API 的流类。例如,你可以创建网络流、从压缩文件读取的流等等。
295
296 RapidJSON 利用模板结合不同的类型。只要一个类包含所有所需的接口,就可以作为一个流。流的接合定义在 `rapidjson/rapidjson.h` 的注释里:
297
298 ~~~~~~~~~~cpp
299 concept Stream {
300 typename Ch; //!< 流的字符类型
301
302 //! 从流读取当前字符,不移动读取指针(read cursor)
303 Ch Peek() const;
304
305 //! 从流读取当前字符,移动读取指针至下一字符。
306 Ch Take();
307
308 //! 获取读取指针。
309 //! \return 从开始以来所读过的字符数量。
310 size_t Tell();
311
312 //! 从当前读取指针开始写入操作。
313 //! \return 返回开始写入的指针。
314 Ch* PutBegin();
315
316 //! 写入一个字符。
317 void Put(Ch c);
318
319 //! 清空缓冲区。
320 void Flush();
321
322 //! 完成写作操作。
323 //! \param begin PutBegin() 返回的开始写入指针。
324 //! \return 已写入的字符数量。
325 size_t PutEnd(Ch* begin);
326 }
327 ~~~~~~~~~~
328
329 输入流必须实现 `Peek()`、`Take()` 及 `Tell()`。
330 输出流必须实现 `Put()` 及 `Flush()`。
331 `PutBegin()` 及 `PutEnd()` 是特殊的接口,仅用于原位(*in situ*)解析。一般的流不需实现它们。然而,即使接口不需用于某些流,仍然需要提供空实现,否则会产生编译错误。
332
333 ## 例子:istream 的包装类 {#ExampleIStreamWrapper}
334
335 以下的简单例子是 `std::istream` 的包装类,它只需现 3 个函数。
336
337 ~~~~~~~~~~cpp
338 class MyIStreamWrapper {
339 public:
340 typedef char Ch;
341
342 MyIStreamWrapper(std::istream& is) : is_(is) {
343 }
344
345 Ch Peek() const { // 1
346 int c = is_.peek();
347 return c == std::char_traits<char>::eof() ? '\0' : (Ch)c;
348 }
349
350 Ch Take() { // 2
351 int c = is_.get();
352 return c == std::char_traits<char>::eof() ? '\0' : (Ch)c;
353 }
354
355 size_t Tell() const { return (size_t)is_.tellg(); } // 3
356
357 Ch* PutBegin() { assert(false); return 0; }
358 void Put(Ch) { assert(false); }
359 void Flush() { assert(false); }
360 size_t PutEnd(Ch*) { assert(false); return 0; }
361
362 private:
363 MyIStreamWrapper(const MyIStreamWrapper&);
364 MyIStreamWrapper& operator=(const MyIStreamWrapper&);
365
366 std::istream& is_;
367 };
368 ~~~~~~~~~~
369
370 使用者能用它来包装 `std::stringstream`、`std::ifstream` 的实例。
371
372 ~~~~~~~~~~cpp
373 const char* json = "[1,2,3,4]";
374 std::stringstream ss(json);
375 MyIStreamWrapper is(ss);
376
377 Document d;
378 d.ParseStream(is);
379 ~~~~~~~~~~
380
381 但要注意,由于标准库的内部开销问,此实现的性能可能不如 RapidJSON 的内存/文件流。
382
383 ## 例子:ostream 的包装类 {#ExampleOStreamWrapper}
384
385 以下的例子是 `std::istream` 的包装类,它只需实现 2 个函数。
386
387 ~~~~~~~~~~cpp
388 class MyOStreamWrapper {
389 public:
390 typedef char Ch;
391
392 OStreamWrapper(std::ostream& os) : os_(os) {
393 }
394
395 Ch Peek() const { assert(false); return '\0'; }
396 Ch Take() { assert(false); return '\0'; }
397 size_t Tell() const { }
398
399 Ch* PutBegin() { assert(false); return 0; }
400 void Put(Ch c) { os_.put(c); } // 1
401 void Flush() { os_.flush(); } // 2
402 size_t PutEnd(Ch*) { assert(false); return 0; }
403
404 private:
405 MyOStreamWrapper(const MyOStreamWrapper&);
406 MyOStreamWrapper& operator=(const MyOStreamWrapper&);
407
408 std::ostream& os_;
409 };
410 ~~~~~~~~~~
411
412 使用者能用它来包装 `std::stringstream`、`std::ofstream` 的实例。
413
414 ~~~~~~~~~~cpp
415 Document d;
416 // ...
417
418 std::stringstream ss;
419 MyOStreamWrapper os(ss);
420
421 Writer<MyOStreamWrapper> writer(os);
422 d.Accept(writer);
423 ~~~~~~~~~~
424
425 但要注意,由于标准库的内部开销问,此实现的性能可能不如 RapidJSON 的内存/文件流。
426
427 # 总结 {#Summary}
428
429 本节描述了 RapidJSON 提供的各种流的类。内存流很简单。若 JSON 存储在文件中,文件流可减少 JSON 解析及生成所需的内存量。编码流在字节流和字符流之间作转换。最后,使用者可使用一个简单接口创建自定义的流。