| 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 解析及生成所需的内存量。编码流在字节流和字符流之间作转换。最后,使用者可使用一个简单接口创建自定义的流。 |