1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
|
<!-- HTML header for doxygen 1.8.7-->
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<meta name="generator" content="Doxygen 1.8.13"/>
<title>RapidJSON: 流</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<link href="navtree.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="resize.js"></script>
<script type="text/javascript" src="navtreedata.js"></script>
<script type="text/javascript" src="navtree.js"></script>
<script type="text/javascript">
$(document).ready(initResizable);
</script>
<link href="search/search.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="search/searchdata.js"></script>
<script type="text/javascript" src="search/search.js"></script>
<script type="text/javascript">
$(document).ready(function() { init_search(); });
</script>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
<link href="doxygenextra.css" rel="stylesheet" type="text/css"/>
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="topbanner"><a href="https://github.com/miloyip/rapidjson" title="RapidJSON GitHub"><i class="githublogo"></i></a></div>
<div id="MSearchBox" class="MSearchBoxInactive">
<span class="left">
<img id="MSearchSelect" src="search/mag_sel.png"
onmouseover="return searchBox.OnSearchSelectShow()"
onmouseout="return searchBox.OnSearchSelectHide()"
alt=""/>
<input type="text" id="MSearchField" value="搜索" accesskey="S"
onfocus="searchBox.OnSearchFieldFocus(true)"
onblur="searchBox.OnSearchFieldFocus(false)"
onkeyup="searchBox.OnSearchFieldChange(event)"/>
</span><span class="right">
<a id="MSearchClose" href="javascript:searchBox.CloseResultsWindow()"><img id="MSearchCloseImg" border="0" src="search/close.png" alt=""/></a>
</span>
</div>
<!-- end header part -->
<!-- 制作者 Doxygen 1.8.13 -->
<script type="text/javascript">
var searchBox = new SearchBox("searchBox", "search",false,'搜索');
</script>
</div><!-- top -->
<div id="side-nav" class="ui-resizable side-nav-resizable">
<div id="nav-tree">
<div id="nav-tree-contents">
<div id="nav-sync" class="sync"></div>
</div>
</div>
<div id="splitbar" style="-moz-user-select:none;"
class="ui-resizable-handle">
</div>
</div>
<script type="text/javascript">
$(document).ready(function(){initNavTree('md_doc_stream_8zh-cn.html','');});
</script>
<div id="doc-content">
<!-- window showing the filter options -->
<div id="MSearchSelectWindow"
onmouseover="return searchBox.OnSearchSelectShow()"
onmouseout="return searchBox.OnSearchSelectHide()"
onkeydown="return searchBox.OnSearchSelectKey(event)">
</div>
<!-- iframe showing the search results (closed by default) -->
<div id="MSearchResultsWindow">
<iframe src="javascript:void(0)" frameborder="0"
name="MSearchResults" id="MSearchResults">
</iframe>
</div>
<div class="header">
<div class="headertitle">
<div class="title">流 </div> </div>
</div><!--header-->
<div class="contents">
<div class="toc"><h3>目录</h3>
<ul><li class="level1"><a href="#MemoryStreams">内存流</a><ul><li class="level2"><a href="#StringStream">StringStream（输入）</a></li>
<li class="level2"><a href="#StringBuffer">StringBuffer（输出）</a></li>
</ul>
</li>
<li class="level1"><a href="#FileStreams">文件流</a><ul><li class="level2"><a href="#FileReadStream">FileReadStream（输入）</a></li>
<li class="level2"><a href="#FileWriteStream">FileWriteStream（输出）</a></li>
</ul>
</li>
<li class="level1"><a href="#iostreamWrapper">iostream 包装类</a><ul><li class="level2"><a href="#IStreamWrapper">IStreamWrapper</a></li>
<li class="level2"><a href="#OStreamWrapper">OStreamWrapper</a></li>
</ul>
</li>
<li class="level1"><a href="#EncodedStreams">编码流</a><ul><li class="level2"><a href="#EncodedInputStream">EncodedInputStream</a></li>
<li class="level2"><a href="#EncodedOutputStream">EncodedOutputStream</a></li>
<li class="level2"><a href="#AutoUTFInputStream">AutoUTFInputStream</a></li>
<li class="level2"><a href="#AutoUTFOutputStream">AutoUTFOutputStream</a></li>
</ul>
</li>
<li class="level1"><a href="#CustomStream">自定义流</a><ul><li class="level2"><a href="#ExampleIStreamWrapper">例子：istream 的包装类</a></li>
<li class="level2"><a href="#ExampleOStreamWrapper">例子：ostream 的包装类</a></li>
</ul>
</li>
<li class="level1"><a href="#Summary">总结</a></li>
</ul>
</div>
<div class="textblock"><p>在 RapidJSON 中，<code><a class="el" href="classrapidjson_1_1_stream.html" title="Concept for reading and writing characters. ">rapidjson::Stream</a></code> 是用於读写 JSON 的概念（概念是指 C++ 的 concept）。在这里我们先介绍如何使用 RapidJSON 提供的各种流。然后再看看如何自行定义流。</p>
<h1><a class="anchor" id="MemoryStreams"></a>
内存流</h1>
<p>内存流把 JSON 存储在内存之中。</p>
<h2><a class="anchor" id="StringStream"></a>
StringStream（输入）</h2>
<p><code>StringStream</code> 是最基本的输入流，它表示一个完整的、只读的、存储于内存的 JSON。它在 <code><a class="el" href="rapidjson_8h.html" title="common definitions and configuration ">rapidjson/rapidjson.h</a></code> 中定义。</p>
<div class="fragment"><div class="line"><span class="preprocessor">#include "<a class="code" href="document_8h.html">rapidjson/document.h</a>"</span> <span class="comment">// 会包含 "rapidjson/rapidjson.h"</span></div><div class="line"></div><div class="line"><span class="keyword">using namespace </span><a class="code" href="namespacerapidjson.html">rapidjson</a>;</div><div class="line"></div><div class="line"><span class="comment">// ...</span></div><div class="line"><span class="keyword">const</span> <span class="keywordtype">char</span> json[] = <span class="stringliteral">"[1, 2, 3, 4]"</span>;</div><div class="line"><a class="code" href="structrapidjson_1_1_generic_string_stream.html">StringStream</a> s(json);</div><div class="line"></div><div class="line"><a class="code" href="classrapidjson_1_1_generic_document.html">Document</a> d;</div><div class="line">d.<a class="code" href="classrapidjson_1_1_generic_document.html#a3ae97682cf04685c7db9d89ebc399b85">ParseStream</a>(s);</div></div><!-- fragment --><p>由于这是非常常用的用法，RapidJSON 提供 <code>Document::Parse(const char*)</code> 去做完全相同的事情：</p>
<div class="fragment"><div class="line"><span class="comment">// ...</span></div><div class="line"><span class="keyword">const</span> <span class="keywordtype">char</span> json[] = <span class="stringliteral">"[1, 2, 3, 4]"</span>;</div><div class="line"><a class="code" href="namespacerapidjson.html#ace11b5b575baf1cccd5ba5f8586dcdc8">Document</a> d;</div><div class="line">d.<a class="code" href="classrapidjson_1_1_generic_document.html#aea842b533a858c9a3861451ad9e8642c">Parse</a>(json);</div></div><!-- fragment --><p>需要注意，<code>StringStream</code> 是 <code>GenericStringStream<UTF8<> ></code> 的 typedef，使用者可用其他编码类去代表流所使用的字符集。</p>
<h2><a class="anchor" id="StringBuffer"></a>
StringBuffer（输出）</h2>
<p><code>StringBuffer</code> 是一个简单的输出流。它分配一个内存缓冲区，供写入整个 JSON。可使用 <code>GetString()</code> 来获取该缓冲区。</p>
<div class="fragment"><div class="line"><span class="preprocessor">#include "rapidjson/stringbuffer.h"</span></div><div class="line"></div><div class="line"><a class="code" href="namespacerapidjson.html#ac0765ea91f41539645c4b78689d03f21">StringBuffer</a> buffer;</div><div class="line">Writer<StringBuffer> writer(buffer);</div><div class="line">d.Accept(writer);</div><div class="line"></div><div class="line"><span class="keyword">const</span> <span class="keywordtype">char</span>* output = buffer.GetString();</div></div><!-- fragment --><p>当缓冲区满溢，它将自动增加容量。缺省容量是 256 个字符（UTF8 是 256 字节，UTF16 是 512 字节等）。使用者能自行提供分配器及初始容量。</p>
<div class="fragment"><div class="line"><a class="code" href="namespacerapidjson.html#ac0765ea91f41539645c4b78689d03f21">StringBuffer</a> buffer1(0, 1024); <span class="comment">// 使用它的分配器，初始大小 = 1024</span></div><div class="line"><a class="code" href="namespacerapidjson.html#ac0765ea91f41539645c4b78689d03f21">StringBuffer</a> buffer2(allocator, 1024);</div></div><!-- fragment --><p>如无设置分配器，<code>StringBuffer</code> 会自行实例化一个内部分配器。</p>
<p>相似地，<code>StringBuffer</code> 是 <code>GenericStringBuffer<UTF8<> ></code> 的 typedef。</p>
<h1><a class="anchor" id="FileStreams"></a>
文件流</h1>
<p>当要从文件解析一个 JSON，你可以把整个 JSON 读入内存并使用上述的 <code>StringStream</code>。</p>
<p>然而，若 JSON 很大，或是内存有限，你可以改用 <code>FileReadStream</code>。它只会从文件读取一部分至缓冲区，然后让那部分被解析。若缓冲区的字符都被读完，它会再从文件读取下一部分。</p>
<h2><a class="anchor" id="FileReadStream"></a>
FileReadStream（输入）</h2>
<p><code>FileReadStream</code> 通过 <code>FILE</code> 指针读取文件。使用者需要提供一个缓冲区。</p>
<div class="fragment"><div class="line"><span class="preprocessor">#include "rapidjson/filereadstream.h"</span></div><div class="line"><span class="preprocessor">#include <cstdio></span></div><div class="line"></div><div class="line"><span class="keyword">using namespace </span><a class="code" href="namespacerapidjson.html">rapidjson</a>;</div><div class="line"></div><div class="line">FILE* fp = fopen(<span class="stringliteral">"big.json"</span>, <span class="stringliteral">"rb"</span>); <span class="comment">// 非 Windows 平台使用 "r"</span></div><div class="line"></div><div class="line"><span class="keywordtype">char</span> readBuffer[65536];</div><div class="line"><a class="code" href="classrapidjson_1_1_file_read_stream.html">FileReadStream</a> is(fp, readBuffer, <span class="keyword">sizeof</span>(readBuffer));</div><div class="line"></div><div class="line"><a class="code" href="classrapidjson_1_1_generic_document.html">Document</a> d;</div><div class="line">d.<a class="code" href="classrapidjson_1_1_generic_document.html#a3ae97682cf04685c7db9d89ebc399b85">ParseStream</a>(is);</div><div class="line"></div><div class="line">fclose(fp);</div></div><!-- fragment --><p>与 <code>StringStreams</code> 不一样，<code>FileReadStream</code> 是一个字节流。它不处理编码。若文件并非 UTF-8 编码，可以把字节流用 <code>EncodedInputStream</code> 包装。我们很快会讨论这个问题。</p>
<p>除了读取文件，使用者也可以使用 <code>FileReadStream</code> 来读取 <code>stdin</code>。</p>
<h2><a class="anchor" id="FileWriteStream"></a>
FileWriteStream（输出）</h2>
<p><code>FileWriteStream</code> 是一个含缓冲功能的输出流。它的用法与 <code>FileReadStream</code> 非常相似。</p>
<div class="fragment"><div class="line"><span class="preprocessor">#include "rapidjson/filewritestream.h"</span></div><div class="line"><span class="preprocessor">#include <cstdio></span></div><div class="line"></div><div class="line"><span class="keyword">using namespace </span><a class="code" href="namespacerapidjson.html">rapidjson</a>;</div><div class="line"></div><div class="line"><a class="code" href="classrapidjson_1_1_generic_document.html">Document</a> d;</div><div class="line">d.<a class="code" href="classrapidjson_1_1_generic_document.html#aea842b533a858c9a3861451ad9e8642c">Parse</a>(json);</div><div class="line"><span class="comment">// ...</span></div><div class="line"></div><div class="line">FILE* fp = fopen(<span class="stringliteral">"output.json"</span>, <span class="stringliteral">"wb"</span>); <span class="comment">// 非 Windows 平台使用 "w"</span></div><div class="line"></div><div class="line"><span class="keywordtype">char</span> writeBuffer[65536];</div><div class="line"><a class="code" href="classrapidjson_1_1_file_write_stream.html">FileWriteStream</a> os(fp, writeBuffer, <span class="keyword">sizeof</span>(writeBuffer));</div><div class="line"></div><div class="line"><a class="code" href="classrapidjson_1_1_writer.html">Writer<FileWriteStream></a> writer(os);</div><div class="line">d.<a class="code" href="classrapidjson_1_1_generic_value.html#ad3ebfa73796f4db4836ec47c2261700c">Accept</a>(writer);</div><div class="line"></div><div class="line">fclose(fp);</div></div><!-- fragment --><p>它也可以把输出导向 <code>stdout</code>。</p>
<h1><a class="anchor" id="iostreamWrapper"></a>
iostream 包装类</h1>
<p>基于用户的要求，RapidJSON 提供了正式的 <code>std::basic_istream</code> 和 <code>std::basic_ostream</code> 包装类。然而，请注意其性能会大大低于以上的其他流。</p>
<h2><a class="anchor" id="IStreamWrapper"></a>
IStreamWrapper</h2>
<p><code>IStreamWrapper</code> 把任何继承自 <code>std::istream</code> 的类（如 <code>std::istringstream</code>、<code>std::stringstream</code>、<code>std::ifstream</code>、<code>std::fstream</code>）包装成 RapidJSON 的输入流。</p>
<div class="fragment"><div class="line"><span class="preprocessor">#include <<a class="code" href="document_8h.html">rapidjson/document.h</a>></span></div><div class="line"><span class="preprocessor">#include <rapidjson/istreamwrapper.h></span></div><div class="line"><span class="preprocessor">#include <fstream></span></div><div class="line"></div><div class="line"><span class="keyword">using namespace </span><a class="code" href="namespacerapidjson.html">rapidjson</a>;</div><div class="line"><span class="keyword">using namespace </span>std;</div><div class="line"></div><div class="line">ifstream ifs(<span class="stringliteral">"test.json"</span>);</div><div class="line"><a class="code" href="classrapidjson_1_1_basic_i_stream_wrapper.html">IStreamWrapper</a> isw(ifs);</div><div class="line"></div><div class="line"><a class="code" href="classrapidjson_1_1_generic_document.html">Document</a> d;</div><div class="line">d.<a class="code" href="classrapidjson_1_1_generic_document.html#a3ae97682cf04685c7db9d89ebc399b85">ParseStream</a>(isw);</div></div><!-- fragment --><p>对于继承自 <code>std::wistream</code> 的类，则使用 <code>WIStreamWrapper</code>。</p>
<h2><a class="anchor" id="OStreamWrapper"></a>
OStreamWrapper</h2>
<p>相似地，<code>OStreamWrapper</code> 把任何继承自 <code>std::ostream</code> 的类（如 <code>std::ostringstream</code>、<code>std::stringstream</code>、<code>std::ofstream</code>、<code>std::fstream</code>）包装成 RapidJSON 的输出流。</p>
<div class="fragment"><div class="line"><span class="preprocessor">#include <<a class="code" href="document_8h.html">rapidjson/document.h</a>></span></div><div class="line"><span class="preprocessor">#include <rapidjson/ostreamwrapper.h></span></div><div class="line"><span class="preprocessor">#include <rapidjson/writer.h></span></div><div class="line"><span class="preprocessor">#include <fstream></span></div><div class="line"></div><div class="line"><span class="keyword">using namespace </span><a class="code" href="namespacerapidjson.html">rapidjson</a>;</div><div class="line"><span class="keyword">using namespace </span>std;</div><div class="line"></div><div class="line"><a class="code" href="classrapidjson_1_1_generic_document.html">Document</a> d;</div><div class="line">d.<a class="code" href="classrapidjson_1_1_generic_document.html#aea842b533a858c9a3861451ad9e8642c">Parse</a>(json);</div><div class="line"></div><div class="line"><span class="comment">// ...</span></div><div class="line"></div><div class="line">ofstream ofs(<span class="stringliteral">"output.json"</span>);</div><div class="line"><a class="code" href="classrapidjson_1_1_basic_o_stream_wrapper.html">OStreamWrapper</a> osw(ofs);</div><div class="line"></div><div class="line"><a class="code" href="classrapidjson_1_1_writer.html">Writer<OStreamWrapper></a> writer(osw);</div><div class="line">d.<a class="code" href="classrapidjson_1_1_generic_value.html#ad3ebfa73796f4db4836ec47c2261700c">Accept</a>(writer);</div></div><!-- fragment --><p>对于继承自 <code>std::wistream</code> 的类，则使用 <code>WIStreamWrapper</code>。</p>
<h1><a class="anchor" id="EncodedStreams"></a>
编码流</h1>
<p>编码流（encoded streams）本身不存储 JSON，它们是通过包装字节流来提供基本的编码／解码功能。</p>
<p>如上所述，我们可以直接读入 UTF-8 字节流。然而，UTF-16 及 UTF-32 有字节序（endian）问题。要正确地处理字节序，需要在读取时把字节转换成字符（如对 UTF-16 使用 <code>wchar_t</code>），以及在写入时把字符转换为字节。</p>
<p>除此以外，我们也需要处理 <a href="http://en.wikipedia.org/wiki/Byte_order_mark">字节顺序标记（byte order mark, BOM）</a>。当从一个字节流读取时，需要检测 BOM，或者仅仅是把存在的 BOM 消去。当把 JSON 写入字节流时，也可选择写入 BOM。</p>
<p>若一个流的编码在编译期已知，你可使用 <code>EncodedInputStream</code> 及 <code>EncodedOutputStream</code>。若一个流可能存储 UTF-8、UTF-16LE、UTF-16BE、UTF-32LE、UTF-32BE 的 JSON，并且编码只能在运行时得知，你便可以使用 <code>AutoUTFInputStream</code> 及 <code>AutoUTFOutputStream</code>。这些流定义在 <code><a class="el" href="encodedstream_8h_source.html">rapidjson/encodedstream.h</a></code>。</p>
<p>注意到，这些编码流可以施于文件以外的流。例如，你可以用编码流包装内存中的文件或自定义的字节流。</p>
<h2><a class="anchor" id="EncodedInputStream"></a>
EncodedInputStream</h2>
<p><code>EncodedInputStream</code> 含两个模板参数。第一个是 <code>Encoding</code> 类型，例如定义于 <code><a class="el" href="encodings_8h_source.html">rapidjson/encodings.h</a></code> 的 <code>UTF8</code>、<code>UTF16LE</code>。第二个参数是被包装的流的类型。</p>
<div class="fragment"><div class="line"><span class="preprocessor">#include "<a class="code" href="document_8h.html">rapidjson/document.h</a>"</span></div><div class="line"><span class="preprocessor">#include "rapidjson/filereadstream.h"</span> <span class="comment">// FileReadStream</span></div><div class="line"><span class="preprocessor">#include "rapidjson/encodedstream.h"</span> <span class="comment">// EncodedInputStream</span></div><div class="line"><span class="preprocessor">#include <cstdio></span></div><div class="line"></div><div class="line"><span class="keyword">using namespace </span><a class="code" href="namespacerapidjson.html">rapidjson</a>;</div><div class="line"></div><div class="line">FILE* fp = fopen(<span class="stringliteral">"utf16le.json"</span>, <span class="stringliteral">"rb"</span>); <span class="comment">// 非 Windows 平台使用 "r"</span></div><div class="line"></div><div class="line"><span class="keywordtype">char</span> readBuffer[256];</div><div class="line"><a class="code" href="classrapidjson_1_1_file_read_stream.html">FileReadStream</a> bis(fp, readBuffer, <span class="keyword">sizeof</span>(readBuffer));</div><div class="line"></div><div class="line"><a class="code" href="classrapidjson_1_1_encoded_input_stream.html">EncodedInputStream<UTF16LE<></a>, <a class="code" href="classrapidjson_1_1_file_read_stream.html">FileReadStream</a>> eis(bis); <span class="comment">// 用 eis 包装 bis</span></div><div class="line"></div><div class="line"><a class="code" href="classrapidjson_1_1_generic_document.html">Document</a> d; <span class="comment">// Document 为 GenericDocument<UTF8<> > </span></div><div class="line">d.<a class="code" href="classrapidjson_1_1_generic_document.html#a3ae97682cf04685c7db9d89ebc399b85">ParseStream</a><0, <a class="code" href="structrapidjson_1_1_u_t_f16_l_e.html">UTF16LE<></a> >(eis); <span class="comment">// 把 UTF-16LE 文件解析至内存中的 UTF-8</span></div><div class="line"></div><div class="line">fclose(fp);</div></div><!-- fragment --><h2><a class="anchor" id="EncodedOutputStream"></a>
EncodedOutputStream</h2>
<p><code>EncodedOutputStream</code> 也是相似的，但它的构造函数有一个 <code>bool putBOM</code> 参数，用于控制是否在输出字节流写入 BOM。</p>
<div class="fragment"><div class="line"><span class="preprocessor">#include "rapidjson/filewritestream.h"</span> <span class="comment">// FileWriteStream</span></div><div class="line"><span class="preprocessor">#include "rapidjson/encodedstream.h"</span> <span class="comment">// EncodedOutputStream</span></div><div class="line"><span class="preprocessor">#include <cstdio></span></div><div class="line"></div><div class="line"><a class="code" href="namespacerapidjson.html#ace11b5b575baf1cccd5ba5f8586dcdc8">Document</a> d; <span class="comment">// Document 为 GenericDocument<UTF8<> > </span></div><div class="line"><span class="comment">// ...</span></div><div class="line"></div><div class="line">FILE* fp = fopen(<span class="stringliteral">"output_utf32le.json"</span>, <span class="stringliteral">"wb"</span>); <span class="comment">// 非 Windows 平台使用 "w"</span></div><div class="line"></div><div class="line"><span class="keywordtype">char</span> writeBuffer[256];</div><div class="line">FileWriteStream bos(fp, writeBuffer, <span class="keyword">sizeof</span>(writeBuffer));</div><div class="line"></div><div class="line"><span class="keyword">typedef</span> EncodedOutputStream<UTF32LE<>, FileWriteStream> OutputStream;</div><div class="line">OutputStream eos(bos, <span class="keyword">true</span>); <span class="comment">// 写入 BOM</span></div><div class="line"></div><div class="line">Writer<OutputStream, UTF32LE<>, UTF8<>> writer(eos);</div><div class="line">d.Accept(writer); <span class="comment">// 这里从内存的 UTF-8 生成 UTF32-LE 文件</span></div><div class="line"></div><div class="line">fclose(fp);</div></div><!-- fragment --><h2><a class="anchor" id="AutoUTFInputStream"></a>
AutoUTFInputStream</h2>
<p>有时候，应用软件可能需要㲃理所有可支持的 JSON 编码。<code>AutoUTFInputStream</code> 会先使用 BOM 来检测编码。若 BOM 不存在，它便会使用合法 JSON 的特性来检测。若两种方法都失败，它就会倒退至构造函数提供的 UTF 类型。</p>
<p>由于字符（编码单元／code unit）可能是 8 位、16 位或 32 位，<code>AutoUTFInputStream</code> 需要一个能至少储存 32 位的字符类型。我们可以使用 <code>unsigned</code> 作为模板参数：</p>
<div class="fragment"><div class="line"><span class="preprocessor">#include "<a class="code" href="document_8h.html">rapidjson/document.h</a>"</span></div><div class="line"><span class="preprocessor">#include "rapidjson/filereadstream.h"</span> <span class="comment">// FileReadStream</span></div><div class="line"><span class="preprocessor">#include "rapidjson/encodedstream.h"</span> <span class="comment">// AutoUTFInputStream</span></div><div class="line"><span class="preprocessor">#include <cstdio></span></div><div class="line"></div><div class="line"><span class="keyword">using namespace </span><a class="code" href="namespacerapidjson.html">rapidjson</a>;</div><div class="line"></div><div class="line">FILE* fp = fopen(<span class="stringliteral">"any.json"</span>, <span class="stringliteral">"rb"</span>); <span class="comment">// 非 Windows 平台使用 "r"</span></div><div class="line"></div><div class="line"><span class="keywordtype">char</span> readBuffer[256];</div><div class="line"><a class="code" href="classrapidjson_1_1_file_read_stream.html">FileReadStream</a> bis(fp, readBuffer, <span class="keyword">sizeof</span>(readBuffer));</div><div class="line"></div><div class="line"><a class="code" href="classrapidjson_1_1_auto_u_t_f_input_stream.html">AutoUTFInputStream<unsigned, FileReadStream></a> eis(bis); <span class="comment">// 用 eis 包装 bis</span></div><div class="line"></div><div class="line"><a class="code" href="classrapidjson_1_1_generic_document.html">Document</a> d; <span class="comment">// Document 为 GenericDocument<UTF8<> > </span></div><div class="line">d.<a class="code" href="classrapidjson_1_1_generic_document.html#a3ae97682cf04685c7db9d89ebc399b85">ParseStream</a><0, <a class="code" href="structrapidjson_1_1_auto_u_t_f.html">AutoUTF<unsigned></a> >(eis); <span class="comment">// 把任何 UTF 编码的文件解析至内存中的 UTF-8</span></div><div class="line"></div><div class="line">fclose(fp);</div></div><!-- fragment --><p>当要指定流的编码，可使用上面例子中 <code>ParseStream()</code> 的参数 <code>AutoUTF<CharType></code>。</p>
<p>你可以使用 <code>UTFType GetType()</code> 去获取 UTF 类型，并且用 <code>HasBOM()</code> 检测输入流是否含有 BOM。</p>
<h2><a class="anchor" id="AutoUTFOutputStream"></a>
AutoUTFOutputStream</h2>
<p>相似地，要在运行时选择输出的编码，我们可使用 <code>AutoUTFOutputStream</code>。这个类本身并非「自动」。你需要在运行时指定 UTF 类型，以及是否写入 BOM。</p>
<div class="fragment"><div class="line"><span class="keyword">using namespace </span><a class="code" href="namespacerapidjson.html">rapidjson</a>;</div><div class="line"></div><div class="line"><span class="keywordtype">void</span> WriteJSONFile(FILE* fp, <a class="code" href="namespacerapidjson.html#a4aacabc0f8cea1cd628f466d890773eb">UTFType</a> type, <span class="keywordtype">bool</span> putBOM, <span class="keyword">const</span> <a class="code" href="classrapidjson_1_1_generic_document.html">Document</a>& d) {</div><div class="line"> <span class="keywordtype">char</span> writeBuffer[256];</div><div class="line"> <a class="code" href="classrapidjson_1_1_file_write_stream.html">FileWriteStream</a> bos(fp, writeBuffer, <span class="keyword">sizeof</span>(writeBuffer));</div><div class="line"></div><div class="line"> <span class="keyword">typedef</span> <a class="code" href="classrapidjson_1_1_auto_u_t_f_output_stream.html">AutoUTFOutputStream<unsigned, FileWriteStream></a> OutputStream;</div><div class="line"> OutputStream eos(bos, type, putBOM);</div><div class="line"></div><div class="line"> <a class="code" href="classrapidjson_1_1_writer.html">Writer<OutputStream, UTF8<></a>, <a class="code" href="structrapidjson_1_1_auto_u_t_f.html">AutoUTF<></a> > writer;</div><div class="line"> d.<a class="code" href="classrapidjson_1_1_generic_value.html#ad3ebfa73796f4db4836ec47c2261700c">Accept</a>(writer);</div><div class="line">}</div></div><!-- fragment --><p><code>AutoUTFInputStream</code>／<code>AutoUTFOutputStream</code> 是比 <code>EncodedInputStream</code>／<code>EncodedOutputStream</code> 方便。但前者会产生一点运行期额外开销。</p>
<h1><a class="anchor" id="CustomStream"></a>
自定义流</h1>
<p>除了内存／文件流，使用者可创建自行定义适配 RapidJSON API 的流类。例如，你可以创建网络流、从压缩文件读取的流等等。</p>
<p>RapidJSON 利用模板结合不同的类型。只要一个类包含所有所需的接口，就可以作为一个流。流的接合定义在 <code><a class="el" href="rapidjson_8h.html" title="common definitions and configuration ">rapidjson/rapidjson.h</a></code> 的注释里：</p>
<div class="fragment"><div class="line">concept Stream {</div><div class="line"> <span class="keyword">typename</span> Ch; <span class="comment">//!< 流的字符类型</span></div><div class="line"><span class="comment"></span><span class="comment"></span></div><div class="line"><span class="comment"> //! 从流读取当前字符，不移动读取指针（read cursor）</span></div><div class="line"><span class="comment"></span> Ch Peek() <span class="keyword">const</span>;</div><div class="line"><span class="comment"></span></div><div class="line"><span class="comment"> //! 从流读取当前字符，移动读取指针至下一字符。</span></div><div class="line"><span class="comment"></span> Ch Take();</div><div class="line"><span class="comment"></span></div><div class="line"><span class="comment"> //! 获取读取指针。</span></div><div class="line"><span class="comment"> //! \return 从开始以来所读过的字符数量。</span></div><div class="line"><span class="comment"></span> <span class="keywordtype">size_t</span> Tell();</div><div class="line"><span class="comment"></span></div><div class="line"><span class="comment"> //! 从当前读取指针开始写入操作。</span></div><div class="line"><span class="comment"> //! \return 返回开始写入的指针。</span></div><div class="line"><span class="comment"></span> Ch* PutBegin();</div><div class="line"><span class="comment"></span></div><div class="line"><span class="comment"> //! 写入一个字符。</span></div><div class="line"><span class="comment"></span> <span class="keywordtype">void</span> Put(Ch c);</div><div class="line"><span class="comment"></span></div><div class="line"><span class="comment"> //! 清空缓冲区。</span></div><div class="line"><span class="comment"></span> <span class="keywordtype">void</span> Flush();</div><div class="line"><span class="comment"></span></div><div class="line"><span class="comment"> //! 完成写作操作。</span></div><div class="line"><span class="comment"> //! \param begin PutBegin() 返回的开始写入指针。</span></div><div class="line"><span class="comment"> //! \return 已写入的字符数量。</span></div><div class="line"><span class="comment"></span> <span class="keywordtype">size_t</span> PutEnd(Ch* begin);</div><div class="line">}</div></div><!-- fragment --><p>输入流必须实现 <code>Peek()</code>、<code>Take()</code> 及 <code>Tell()</code>。 输出流必须实现 <code>Put()</code> 及 <code>Flush()</code>。 <code>PutBegin()</code> 及 <code>PutEnd()</code> 是特殊的接口，仅用于原位（*in situ*）解析。一般的流不需实现它们。然而，即使接口不需用于某些流，仍然需要提供空实现，否则会产生编译错误。</p>
<h2><a class="anchor" id="ExampleIStreamWrapper"></a>
例子：istream 的包装类</h2>
<p>以下的简单例子是 <code>std::istream</code> 的包装类，它只需现 3 个函数。</p>
<div class="fragment"><div class="line"><span class="keyword">class </span>MyIStreamWrapper {</div><div class="line"><span class="keyword">public</span>:</div><div class="line"> <span class="keyword">typedef</span> <span class="keywordtype">char</span> Ch;</div><div class="line"></div><div class="line"> MyIStreamWrapper(std::istream& is) : is_(is) {</div><div class="line"> }</div><div class="line"></div><div class="line"> Ch Peek()<span class="keyword"> const </span>{ <span class="comment">// 1</span></div><div class="line"> <span class="keywordtype">int</span> c = is_.peek();</div><div class="line"> <span class="keywordflow">return</span> c == std::char_traits<char>::eof() ? <span class="charliteral">'\0'</span> : (Ch)c;</div><div class="line"> }</div><div class="line"></div><div class="line"> Ch Take() { <span class="comment">// 2</span></div><div class="line"> <span class="keywordtype">int</span> c = is_.get();</div><div class="line"> <span class="keywordflow">return</span> c == std::char_traits<char>::eof() ? <span class="charliteral">'\0'</span> : (Ch)c;</div><div class="line"> }</div><div class="line"></div><div class="line"> <span class="keywordtype">size_t</span> Tell()<span class="keyword"> const </span>{ <span class="keywordflow">return</span> (<span class="keywordtype">size_t</span>)is_.tellg(); } <span class="comment">// 3</span></div><div class="line"></div><div class="line"> Ch* PutBegin() { assert(<span class="keyword">false</span>); <span class="keywordflow">return</span> 0; }</div><div class="line"> <span class="keywordtype">void</span> Put(Ch) { assert(<span class="keyword">false</span>); }</div><div class="line"> <span class="keywordtype">void</span> Flush() { assert(<span class="keyword">false</span>); }</div><div class="line"> <span class="keywordtype">size_t</span> PutEnd(Ch*) { assert(<span class="keyword">false</span>); <span class="keywordflow">return</span> 0; }</div><div class="line"></div><div class="line"><span class="keyword">private</span>:</div><div class="line"> MyIStreamWrapper(<span class="keyword">const</span> MyIStreamWrapper&);</div><div class="line"> MyIStreamWrapper& operator=(<span class="keyword">const</span> MyIStreamWrapper&);</div><div class="line"></div><div class="line"> std::istream& is_;</div><div class="line">};</div></div><!-- fragment --><p>使用者能用它来包装 <code>std::stringstream</code>、<code>std::ifstream</code> 的实例。</p>
<div class="fragment"><div class="line"><span class="keyword">const</span> <span class="keywordtype">char</span>* json = <span class="stringliteral">"[1,2,3,4]"</span>;</div><div class="line">std::stringstream ss(json);</div><div class="line">MyIStreamWrapper is(ss);</div><div class="line"></div><div class="line"><a class="code" href="namespacerapidjson.html#ace11b5b575baf1cccd5ba5f8586dcdc8">Document</a> d;</div><div class="line">d.<a class="code" href="classrapidjson_1_1_generic_document.html#a3ae97682cf04685c7db9d89ebc399b85">ParseStream</a>(is);</div></div><!-- fragment --><p>但要注意，由于标准库的内部开销问，此实现的性能可能不如 RapidJSON 的内存／文件流。</p>
<h2><a class="anchor" id="ExampleOStreamWrapper"></a>
例子：ostream 的包装类</h2>
<p>以下的例子是 <code>std::istream</code> 的包装类，它只需实现 2 个函数。</p>
<div class="fragment"><div class="line"><span class="keyword">class </span>MyOStreamWrapper {</div><div class="line"><span class="keyword">public</span>:</div><div class="line"> <span class="keyword">typedef</span> <span class="keywordtype">char</span> Ch;</div><div class="line"></div><div class="line"> OStreamWrapper(std::ostream& os) : os_(os) {</div><div class="line"> }</div><div class="line"></div><div class="line"> Ch Peek()<span class="keyword"> const </span>{ assert(<span class="keyword">false</span>); <span class="keywordflow">return</span> <span class="charliteral">'\0'</span>; }</div><div class="line"> Ch Take() { assert(<span class="keyword">false</span>); <span class="keywordflow">return</span> <span class="charliteral">'\0'</span>; }</div><div class="line"> <span class="keywordtype">size_t</span> Tell()<span class="keyword"> const </span>{ }</div><div class="line"></div><div class="line"> Ch* PutBegin() { assert(<span class="keyword">false</span>); <span class="keywordflow">return</span> 0; }</div><div class="line"> <span class="keywordtype">void</span> Put(Ch c) { os_.put(c); } <span class="comment">// 1</span></div><div class="line"> <span class="keywordtype">void</span> Flush() { os_.flush(); } <span class="comment">// 2</span></div><div class="line"> <span class="keywordtype">size_t</span> PutEnd(Ch*) { assert(<span class="keyword">false</span>); <span class="keywordflow">return</span> 0; }</div><div class="line"></div><div class="line"><span class="keyword">private</span>:</div><div class="line"> MyOStreamWrapper(<span class="keyword">const</span> MyOStreamWrapper&);</div><div class="line"> MyOStreamWrapper& operator=(<span class="keyword">const</span> MyOStreamWrapper&);</div><div class="line"></div><div class="line"> std::ostream& os_;</div><div class="line">};</div></div><!-- fragment --><p>使用者能用它来包装 <code>std::stringstream</code>、<code>std::ofstream</code> 的实例。</p>
<div class="fragment"><div class="line"><a class="code" href="namespacerapidjson.html#ace11b5b575baf1cccd5ba5f8586dcdc8">Document</a> d;</div><div class="line"><span class="comment">// ...</span></div><div class="line"></div><div class="line">std::stringstream ss;</div><div class="line">MyOStreamWrapper os(ss);</div><div class="line"></div><div class="line">Writer<MyOStreamWrapper> writer(os);</div><div class="line">d.Accept(writer);</div></div><!-- fragment --><p>但要注意，由于标准库的内部开销问，此实现的性能可能不如 RapidJSON 的内存／文件流。</p>
<h1><a class="anchor" id="Summary"></a>
总结</h1>
<p>本节描述了 RapidJSON 提供的各种流的类。内存流很简单。若 JSON 存储在文件中，文件流可减少 JSON 解析及生成所需的内存量。编码流在字节流和字符流之间作转换。最后，使用者可使用一个简单接口创建自定义的流。 </p>
</div></div><!-- contents -->
</div><!-- doc-content -->
<!-- HTML footer for doxygen 1.8.7-->
<!-- start footer part -->
<div id="nav-path" class="navpath"><!-- id is needed for treeview function! -->
<ul>
</ul>
</div>
</body>
</html>
|
