在RapidJSON中,rapidjson::Stream
是用於读写JSON的概念(概念是指C++的concept)。在这里我们先介绍如何使用RapidJSON提供的各种流。然后再看看如何自行定义流。
内存流
内存流把JSON存储在内存之中。
StringStream(输入)
StringStream
是最基本的输入流,它表示一个完整的、只读的、存储于内存的JSON。它在rapidjson/rapidjson.h
中定义。
using namespace rapidjson;
const char json[] = "[1, 2, 3, 4]";
由于这是非常常用的用法,RapidJSON提供Document::Parse(const char*)
去做完全相同的事情:
const char json[] = "[1, 2, 3, 4]";
d.Parse(json);
需要注意,StringStream
是GenericStringStream<UTF8<> >
的typedef,使用者可用其他编码类去代表流所使用的字符集。
StringBuffer(输出)
StringBuffer
是一个简单的输出流。它分配一个内存缓冲区,供写入整个JSON。可使用GetString()
来获取该缓冲区。
#include "rapidjson/stringbuffer.h"
Writer<StringBuffer> writer(buffer);
d.Accept(writer);
const char* output = buffer.GetString();
当缓冲区满溢,它将自动增加容量。缺省容量是256个字符(UTF8是256字节,UTF16是512字节等)。使用者能自行提供分配器及初始容量。
如无设置分配器,StringBuffer
会自行实例化一个内部分配器。
相似地,StringBuffer
是GenericStringBuffer<UTF8<> >
的typedef。
文件流
当要从文件解析一个JSON,你可以把整个JSON读入内存并使用上述的StringStream
。
然而,若JSON很大,或是内存有限,你可以改用FileReadStream
。它只会从文件读取一部分至缓冲区,然后让那部分被解析。若缓冲区的字符都被读完,它会再从文件读取下一部分。
FileReadStream(输入)
FileReadStream
通过FILE
指针读取文件。使用者需要提供一个缓冲区。
#include "rapidjson/filereadstream.h"
#include <cstdio>
using namespace rapidjson;
FILE* fp = fopen("big.json", "rb");
char readBuffer[65536];
fclose(fp);
与StringStreams
不一样,FileReadStream
是一个字节流。它不处理编码。若文件并非UTF-8编码,可以把字节流用EncodedInputStream
包装。我们很快会讨论这个问题。
除了读取文件,使用者也可以使用FileReadStream
来读取stdin
。
FileWriteStream(输出)
FileWriteStream
是一个含缓冲功能的输出流。它的用法与FileReadStream
非常相似。
#include "rapidjson/filewritestream.h"
#include <cstdio>
using namespace rapidjson;
FILE* fp = fopen("output.json", "wb");
char writeBuffer[65536];
d.Accept(writer);
fclose(fp);
它也可以把输出导向stdout
。
编码流
编码流(encoded streams)本身不存储JSON,它们是通过包装字节流来提供基本的编码/解码功能。
如上所述,我们可以直接读入UTF-8字节流。然而,UTF-16及UTF-32有字节序(endian)问题。要正确地处理字节序,需要在读取时把字节转换成字符(如对UTF-16使用wchar_t
),以及在写入时把字符转换为字节。
除此以外,我们也需要处理字节顺序标记(byte order mark, BOM)。当从一个字节流读取时,需要检测BOM,或者仅仅是把存在的BOM消去。当把JSON写入字节流时,也可选择写入BOM。
若一个流的编码在编译期已知,你可使用EncodedInputStream
及EncodedOutputStream
。若一个流可能存储UTF-8、UTF-16LE、UTF-16BE、UTF-32LE、UTF-32BE的JSON,并且编码只能在运行时得知,你便可以使用AutoUTFInputStream
及AutoUTFOutputStream
。这些流定义在rapidjson/encodedstream.h
。
注意到,这些编码流可以施于文件以外的流。例如,你可以用编码流包装内存中的文件或自定义的字节流。
EncodedInputStream
EncodedInputStream
含两个模板参数。第一个是Encoding
类型,例如定义于rapidjson/encodings.h
的UTF8
、UTF16LE
。第二个参数是被包装的流的类型。
#include "rapidjson/filereadstream.h"
#include "rapidjson/encodedstream.h"
#include <cstdio>
using namespace rapidjson;
FILE* fp = fopen("utf16le.json", "rb");
char readBuffer[256];
fclose(fp);
EncodedOutputStream
EncodedOutputStream
也是相似的,但它的构造函数有一个bool putBOM
参数,用于控制是否在输出字节流写入BOM。
#include "rapidjson/filewritestream.h"
#include "rapidjson/encodedstream.h"
#include <cstdio>
FILE* fp = fopen("output_utf32le.json", "wb");
char writeBuffer[256];
FileWriteStream bos(fp, writeBuffer, sizeof(writeBuffer));
typedef EncodedOutputStream<UTF32LE<>, FileWriteStream> OutputStream;
OutputStream eos(bos, true);
Writer<OutputStream, UTF32LE<>, UTF8<>> writer(eos);
d.Accept(writer);
fclose(fp);
AutoUTFInputStream
有时候,应用软件可能需要㲃理所有可支持的JSON编码。AutoUTFInputStream
会先使用BOM来检测编码。若BOM不存在,它便会使用合法JSON的特性来检测。若两种方法都失败,它就会倒退至构造函数提供的UTF类型。
由于字符(编码单元/code unit)可能是8位、16位或32位,AutoUTFInputStream
需要一个能至少储存32位的字符类型。我们可以使用unsigned
作为模板参数:
#include "rapidjson/filereadstream.h"
#include "rapidjson/encodedstream.h"
#include <cstdio>
using namespace rapidjson;
FILE* fp = fopen("any.json", "rb");
char readBuffer[256];
fclose(fp);
当要指定流的编码,可使用上面例子中ParseStream()
的参数AutoUTF<CharType>
。
你可以使用UTFType GetType()
去获取UTF类型,并且用HasBOM()
检测输入流是否含有BOM。
AutoUTFOutputStream
相似地,要在运行时选择输出的编码,我们可使用AutoUTFOutputStream
。这个类本身并非「自动」。你需要在运行时指定UTF类型,以及是否写入BOM。
using namespace rapidjson;
void WriteJSONFile(FILE* fp,
UTFType type,
bool putBOM,
const Document& d) {
char writeBuffer[256];
OutputStream eos(bos, type, putBOM);
}
AutoUTFInputStream
/AutoUTFOutputStream
是比EncodedInputStream
/EncodedOutputStream
方便。但前者会产生一点运行期额外开销。
自定义流
除了内存/文件流,使用者可创建自行定义适配RapidJSON API的流类。例如,你可以创建网络流、从压缩文件读取的流等等。
RapidJSON利用模板结合不同的类型。只要一个类包含所有所需的接口,就可以作为一个流。流的接合定义在rapidjson/rapidjson.h
的注释里:
concept Stream {
typename Ch;
Ch Peek() const;
Ch Take();
size_t Tell();
Ch* PutBegin();
void Put(Ch c);
void Flush();
size_t PutEnd(Ch* begin);
}
输入流必须实现Peek()
、Take()
及Tell()
。 输出流必须实现Put()
及Flush()
。 PutBegin()
及PutEnd()
是特殊的接口,仅用于原位(*in situ*)解析。一般的流不需实现它们。然而,即使接口不需用于某些流,仍然需要提供空实现,否则会产生编译错误。
例子:istream的包装类
以下的例子是std::istream
的包装类,它只需现3个函数。
class IStreamWrapper {
public:
typedef char Ch;
IStreamWrapper(std::istream& is) : is_(is) {
}
Ch Peek() const {
int c = is_.peek();
return c == std::char_traits<char>::eof() ? '\0' : (Ch)c;
}
Ch Take() {
int c = is_.get();
return c == std::char_traits<char>::eof() ? '\0' : (Ch)c;
}
size_t Tell() const { return (size_t)is_.tellg(); }
Ch* PutBegin() { assert(false); return 0; }
void Put(Ch) { assert(false); }
void Flush() { assert(false); }
size_t PutEnd(Ch*) { assert(false); return 0; }
private:
IStreamWrapper(const IStreamWrapper&);
IStreamWrapper& operator=(const IStreamWrapper&);
std::istream& is_;
};
使用者能用它来包装std::stringstream
、std::ifstream
的实例。
const char* json = "[1,2,3,4]";
std::stringstream ss(json);
IStreamWrapper is(ss);
但要注意,由于标准库的内部开销问,此实现的性能可能不如RapidJSON的内存/文件流。
例子:ostream的包装类
以下的例子是std::istream
的包装类,它只需实现2个函数。
class OStreamWrapper {
public:
typedef char Ch;
OStreamWrapper(std::ostream& os) : os_(os) {
}
Ch Peek() const { assert(false); return '\0'; }
Ch Take() { assert(false); return '\0'; }
size_t Tell() const { }
Ch* PutBegin() { assert(false); return 0; }
void Put(Ch c) { os_.put(c); }
void Flush() { os_.flush(); }
size_t PutEnd(Ch*) { assert(false); return 0; }
private:
OStreamWrapper(const OStreamWrapper&);
OStreamWrapper& operator=(const OStreamWrapper&);
std::ostream& os_;
};
使用者能用它来包装std::stringstream
、std::ofstream
的实例。
std::stringstream ss;
OSStreamWrapper os(ss);
Writer<OStreamWrapper> writer(os);
d.Accept(writer);
但要注意,由于标准库的内部开销问,此实现的性能可能不如RapidJSON的内存/文件流。
总结
本节描述了RapidJSON提供的各种流的类。内存流很简单。若JSON存储在文件中,文件流可减少JSON解析及生成所需的内存量。编码流在字节流和字符流之间作转换。最后,使用者可使用一个简单接口创建自定义的流。