simdjson 0.2.0 → 0.3.0

data/vendor/simdjson/dependencies/rapidjson/doc/encoding.md

@@ -0,0 +1,146 @@
+# Encoding
+
+According to [ECMA-404](http://www.ecma-international.org/publications/files/ECMA-ST/ECMA-404.pdf),
+
+> (in Introduction) JSON text is a sequence of Unicode code points.
+
+The earlier [RFC4627](http://www.ietf.org/rfc/rfc4627.txt) stated that,
+
+> (in §3) JSON text SHALL be encoded in Unicode.  The default encoding is UTF-8.
+
+> (in §6) JSON may be represented using UTF-8, UTF-16, or UTF-32. When JSON is written in UTF-8, JSON is 8bit compatible.  When JSON is written in UTF-16 or UTF-32, the binary content-transfer-encoding must be used.
+
+RapidJSON supports various encodings. It can also validate the encodings of JSON, and transcoding JSON among encodings. All these features are implemented internally, without the need for external libraries (e.g. [ICU](http://site.icu-project.org/)).
+
+[TOC]
+
+# Unicode {#Unicode}
+From [Unicode's official website](http://www.unicode.org/standard/WhatIsUnicode.html):
+> Unicode provides a unique number for every character, 
+> no matter what the platform,
+> no matter what the program,
+> no matter what the language.
+
+Those unique numbers are called code points, which is in the range `0x0` to `0x10FFFF`.
+
+## Unicode Transformation Format {#UTF}
+
+There are various encodings for storing Unicode code points. These are called Unicode Transformation Format (UTF). RapidJSON supports the most commonly used UTFs, including
+
+* UTF-8: 8-bit variable-width encoding. It maps a code point to 1–4 bytes.
+* UTF-16: 16-bit variable-width encoding. It maps a code point to 1–2 16-bit code units (i.e., 2–4 bytes).
+* UTF-32: 32-bit fixed-width encoding. It directly maps a code point to a single 32-bit code unit (i.e. 4 bytes).
+
+For UTF-16 and UTF-32, the byte order (endianness) does matter. Within computer memory, they are often stored in the computer's endianness. However, when it is stored in file or transferred over network, we need to state the byte order of the byte sequence, either little-endian (LE) or big-endian (BE). 
+
+RapidJSON provide these encodings via the structs in `rapidjson/encodings.h`:
+
+~~~~~~~~~~cpp
+namespace rapidjson {
+
+template<typename CharType = char>
+struct UTF8;
+
+template<typename CharType = wchar_t>
+struct UTF16;
+
+template<typename CharType = wchar_t>
+struct UTF16LE;
+
+template<typename CharType = wchar_t>
+struct UTF16BE;
+
+template<typename CharType = unsigned>
+struct UTF32;
+
+template<typename CharType = unsigned>
+struct UTF32LE;
+
+template<typename CharType = unsigned>
+struct UTF32BE;
+
+} // namespace rapidjson
+~~~~~~~~~~
+
+For processing text in memory, we normally use `UTF8`, `UTF16` or `UTF32`. For processing text via I/O, we may use `UTF8`, `UTF16LE`, `UTF16BE`, `UTF32LE` or `UTF32BE`.
+
+When using the DOM-style API, the `Encoding` template parameter in `GenericValue<Encoding>` and `GenericDocument<Encoding>` indicates the encoding to be used to represent JSON string in memory. So normally we will use `UTF8`, `UTF16` or `UTF32` for this template parameter. The choice depends on operating systems and other libraries that the application is using. For example, Windows API represents Unicode characters in UTF-16, while most Linux distributions and applications prefer UTF-8.
+
+Example of UTF-16 DOM declaration:
+
+~~~~~~~~~~cpp
+typedef GenericDocument<UTF16<> > WDocument;
+typedef GenericValue<UTF16<> > WValue;
+~~~~~~~~~~
+
+For a detail example, please check the example in [DOM's Encoding](doc/stream.md) section.
+
+## Character Type {#CharacterType}
+
+As shown in the declaration, each encoding has a `CharType` template parameter. Actually, it may be a little bit confusing, but each `CharType` stores a code unit, not a character (code point). As mentioned in previous section, a code point may be encoded to 1–4 code units for UTF-8.
+
+For `UTF16(LE|BE)`, `UTF32(LE|BE)`, the `CharType` must be integer type of at least 2 and 4 bytes  respectively.
+
+Note that C++11 introduces `char16_t` and `char32_t`, which can be used for `UTF16` and `UTF32` respectively.
+
+## AutoUTF {#AutoUTF}
+
+Previous encodings are statically bound in compile-time. In other words, user must know exactly which encodings will be used in the memory or streams. However, sometimes we may need to read/write files of different encodings. The encoding needed to be decided in runtime.
+
+`AutoUTF` is an encoding designed for this purpose. It chooses which encoding to be used according to the input or output stream. Currently, it should be used with `EncodedInputStream` and `EncodedOutputStream`.
+
+## ASCII {#ASCII}
+
+Although the JSON standards did not mention about [ASCII](http://en.wikipedia.org/wiki/ASCII), sometimes we would like to write 7-bit ASCII JSON for applications that cannot handle UTF-8. Since any JSON can represent unicode characters in escaped sequence `\uXXXX`, JSON can always be encoded in ASCII.
+
+Here is an example for writing a UTF-8 DOM into ASCII:
+
+~~~~~~~~~~cpp
+using namespace rapidjson;
+Document d; // UTF8<>
+// ...
+StringBuffer buffer;
+Writer<StringBuffer, Document::EncodingType, ASCII<> > writer(buffer);
+d.Accept(writer);
+std::cout << buffer.GetString();
+~~~~~~~~~~
+
+ASCII can be used in input stream. If the input stream contains bytes with values above 127, it will cause `kParseErrorStringInvalidEncoding` error.
+
+ASCII *cannot* be used in memory (encoding of `Document` or target encoding of `Reader`), as it cannot represent Unicode code points.
+
+# Validation & Transcoding {#ValidationTranscoding}
+
+When RapidJSON parses a JSON, it can validate the input JSON, whether it is a valid sequence of a specified encoding. This option can be turned on by adding `kParseValidateEncodingFlag` in `parseFlags` template parameter.
+
+If the input encoding and output encoding is different, `Reader` and `Writer` will automatically transcode (convert) the text. In this case, `kParseValidateEncodingFlag` is not necessary, as it must decode the input sequence. And if the sequence was unable to be decoded, it must be invalid.
+
+## Transcoder {#Transcoder}
+
+Although the encoding functions in RapidJSON are designed for JSON parsing/generation, user may abuse them for transcoding of non-JSON strings.
+
+Here is an example for transcoding a string from UTF-8 to UTF-16:
+
+~~~~~~~~~~cpp
+#include "rapidjson/encodings.h"
+
+using namespace rapidjson;
+
+const char* s = "..."; // UTF-8 string
+StringStream source(s);
+GenericStringBuffer<UTF16<> > target;
+
+bool hasError = false;
+while (source.Peek() != '\0')
+    if (!Transcoder<UTF8<>, UTF16<> >::Transcode(source, target)) {
+        hasError = true;
+        break;
+    }
+
+if (!hasError) {
+    const wchar_t* t = target.GetString();
+    // ...
+}
+~~~~~~~~~~
+
+You may also use `AutoUTF` and the associated streams for setting source/target encoding in runtime.

data/vendor/simdjson/dependencies/rapidjson/doc/encoding.zh-cn.md

@@ -0,0 +1,152 @@
+# 编码
+
+根据 [ECMA-404](http://www.ecma-international.org/publications/files/ECMA-ST/ECMA-404.pdf)：
+
+> (in Introduction) JSON text is a sequence of Unicode code points.
+> 
+> 翻译：JSON 文本是 Unicode 码点的序列。
+
+较早的 [RFC4627](http://www.ietf.org/rfc/rfc4627.txt) 申明：
+
+> (in §3) JSON text SHALL be encoded in Unicode.  The default encoding is UTF-8.
+> 
+> 翻译：JSON 文本应该以 Unicode 编码。缺省的编码为 UTF-8。
+
+> (in §6) JSON may be represented using UTF-8, UTF-16, or UTF-32. When JSON is written in UTF-8, JSON is 8bit compatible.  When JSON is written in UTF-16 or UTF-32, the binary content-transfer-encoding must be used.
+> 
+> 翻译：JSON 可使用 UTF-8、UTF-16 或 UTF-32 表示。当 JSON 以 UTF-8 写入，该 JSON 是 8 位兼容的。当 JSON 以 UTF-16 或 UTF-32 写入，就必须使用二进制的内容传送编码。
+
+RapidJSON 支持多种编码。它也能检查 JSON 的编码，以及在不同编码中进行转码。所有这些功能都是在内部实现，无需使用外部的程序库（如 [ICU](http://site.icu-project.org/)）。
+
+[TOC]
+
+# Unicode {#Unicode}
+根据 [Unicode 的官方网站](http://www.unicode.org/standard/translations/t-chinese.html)：
+>Unicode 给每个字符提供了一个唯一的数字，
+不论是什么平台、
+不论是什么程序、
+不论是什么语言。
+
+这些唯一数字称为码点（code point），其范围介乎 `0x0` 至 `0x10FFFF` 之间。
+
+## Unicode 转换格式 {#UTF}
+
+存储 Unicode 码点有多种编码方式。这些称为 Unicode 转换格式（Unicode Transformation Format, UTF）。RapidJSON 支持最常用的 UTF，包括：
+
+* UTF-8：8 位可变长度编码。它把一个码点映射至 1 至 4 个字节。
+* UTF-16：16 位可变长度编码。它把一个码点映射至 1 至 2 个 16 位编码单元（即 2 至 4 个字节）。
+* UTF-32：32 位固定长度编码。它直接把码点映射至单个 32 位编码单元（即 4 字节）。
+
+对于 UTF-16 及 UTF-32 来说，字节序（endianness）是有影响的。在内存中，它们通常都是以该计算机的字节序来存储。然而，当要储存在文件中或在网上传输，我们需要指明字节序列的字节序，是小端（little endian, LE）还是大端（big-endian, BE）。 
+
+RapidJSON 通过 `rapidjson/encodings.h` 中的 struct 去提供各种编码：
+
+~~~~~~~~~~cpp
+namespace rapidjson {
+
+template<typename CharType = char>
+struct UTF8;
+
+template<typename CharType = wchar_t>
+struct UTF16;
+
+template<typename CharType = wchar_t>
+struct UTF16LE;
+
+template<typename CharType = wchar_t>
+struct UTF16BE;
+
+template<typename CharType = unsigned>
+struct UTF32;
+
+template<typename CharType = unsigned>
+struct UTF32LE;
+
+template<typename CharType = unsigned>
+struct UTF32BE;
+
+} // namespace rapidjson
+~~~~~~~~~~
+
+对于在内存中的文本，我们正常会使用 `UTF8`、`UTF16` 或 `UTF32`。对于处理经过 I/O 的文本，我们可使用 `UTF8`、`UTF16LE`、`UTF16BE`、`UTF32LE` 或 `UTF32BE`。
+
+当使用 DOM 风格的 API，`GenericValue<Encoding>` 及 `GenericDocument<Encoding>` 里的 `Encoding` 模板参数是用于指明内存中存储的 JSON 字符串使用哪种编码。因此通常我们会在此参数中使用 `UTF8`、`UTF16` 或 `UTF32`。如何选择，视乎应用软件所使用的操作系统及其他程序库。例如，Windows API 使用 UTF-16 表示 Unicode 字符，而多数的 Linux 发行版本及应用软件则更喜欢 UTF-8。
+
+使用 UTF-16 的 DOM 声明例子：
+
+~~~~~~~~~~cpp
+typedef GenericDocument<UTF16<> > WDocument;
+typedef GenericValue<UTF16<> > WValue;
+~~~~~~~~~~
+
+可以在 [DOM's Encoding](doc/stream.zh-cn.md) 一节看到更详细的使用例子。
+
+## 字符类型 {#CharacterType}
+
+从之前的声明中可以看到，每个编码都有一个 `CharType` 模板参数。这可能比较容易混淆，实际上，每个 `CharType` 存储一个编码单元，而不是一个字符（码点）。如之前所谈及，在 UTF-8 中一个码点可能会编码成 1 至 4 个编码单元。
+
+对于 `UTF16(LE|BE)` 及 `UTF32(LE|BE)` 来说，`CharType` 必须分别是一个至少 2 及 4 字节的整数类型。
+
+注意 C++11 新添了 `char16_t` 及 `char32_t` 类型，也可分别用于 `UTF16` 及 `UTF32`。
+
+## AutoUTF {#AutoUTF}
+
+上述所介绍的编码都是在编译期静态挷定的。换句话说，使用者必须知道内存或流之中使用了哪种编码。然而，有时候我们可能需要读写不同编码的文件，而且这些编码需要在运行时才能决定。
+
+`AutoUTF` 是为此而设计的编码。它根据输入或输出流来选择使用哪种编码。目前它应该与 `EncodedInputStream` 及 `EncodedOutputStream` 结合使用。
+
+## ASCII {#ASCII}
+
+虽然 JSON 标准并未提及 [ASCII](http://en.wikipedia.org/wiki/ASCII)，有时候我们希望写入 7 位的 ASCII JSON，以供未能处理 UTF-8 的应用程序使用。由于任 JSON 都可以把 Unicode 字符表示为 `\uXXXX` 转义序列，JSON 总是可用 ASCII 来编码。
+
+以下的例子把 UTF-8 的 DOM 写成 ASCII 的 JSON：
+
+~~~~~~~~~~cpp
+using namespace rapidjson;
+Document d; // UTF8<>
+// ...
+StringBuffer buffer;
+Writer<StringBuffer, Document::EncodingType, ASCII<> > writer(buffer);
+d.Accept(writer);
+std::cout << buffer.GetString();
+~~~~~~~~~~
+
+ASCII 可用于输入流。当输入流包含大于 127 的字节，就会导致 `kParseErrorStringInvalidEncoding` 错误。
+
+ASCII * 不能 * 用于内存（`Document` 的编码，或 `Reader` 的目标编码)，因为它不能表示 Unicode 码点。
+
+# 校验及转码 {#ValidationTranscoding}
+
+当 RapidJSON 解析一个 JSON 时，它能校验输入 JSON，判断它是否所标明编码的合法序列。要开启此选项，请把 `kParseValidateEncodingFlag` 加入 `parseFlags` 模板参数。
+
+若输入编码和输出编码并不相同，`Reader` 及 `Writer` 会算把文本转码。在这种情况下，并不需要 `kParseValidateEncodingFlag`，因为它必须解码输入序列。若序列不能被解码，它必然是不合法的。
+
+## 转码器 {#Transcoder}
+
+虽然 RapidJSON 的编码功能是为 JSON 解析／生成而设计，使用者也可以“滥用”它们来为非 JSON 字符串转码。
+
+以下的例子把 UTF-8 字符串转码成 UTF-16：
+
+~~~~~~~~~~cpp
+#include "rapidjson/encodings.h"
+
+using namespace rapidjson;
+
+const char* s = "..."; // UTF-8 string
+StringStream source(s);
+GenericStringBuffer<UTF16<> > target;
+
+bool hasError = false;
+while (source.Peek() != '\0')
+    if (!Transcoder<UTF8<>, UTF16<> >::Transcode(source, target)) {
+        hasError = true;
+        break;
+    }
+
+if (!hasError) {
+    const wchar_t* t = target.GetString();
+    // ...
+}
+~~~~~~~~~~
+
+你也可以用 `AutoUTF` 及对应的流来在运行时设置内源／目的之编码。

data/vendor/simdjson/dependencies/rapidjson/doc/faq.md

@@ -0,0 +1,289 @@
+# FAQ
+
+[TOC]
+
+## General
+
+1. What is RapidJSON?
+
+   RapidJSON is a C++ library for parsing and generating JSON. You may check all [features](doc/features.md) of it.
+
+2. Why is RapidJSON named so?
+
+   It is inspired by [RapidXML](http://rapidxml.sourceforge.net/), which is a fast XML DOM parser.
+
+3. Is RapidJSON similar to RapidXML?
+
+   RapidJSON borrowed some designs of RapidXML, including *in situ* parsing, header-only library. But the two APIs are completely different. Also RapidJSON provide many features that are not in RapidXML.
+
+4. Is RapidJSON free?
+
+   Yes, it is free under MIT license. It can be used in commercial applications. Please check the details in [license.txt](https://github.com/Tencent/rapidjson/blob/master/license.txt).
+
+5. Is RapidJSON small? What are its dependencies? 
+
+   Yes. A simple executable which parses a JSON and prints its statistics is less than 30KB on Windows.
+
+   RapidJSON depends on C++ standard library only.
+
+6. How to install RapidJSON?
+
+   Check [Installation section](https://miloyip.github.io/rapidjson/).
+
+7. Can RapidJSON run on my platform?
+
+   RapidJSON has been tested in many combinations of operating systems, compilers and CPU architecture by the community. But we cannot ensure that it can be run on your particular platform. Building and running the unit test suite will give you the answer.
+
+8. Does RapidJSON support C++03? C++11?
+
+   RapidJSON was firstly implemented for C++03. Later it added optional support of some C++11 features (e.g., move constructor, `noexcept`). RapidJSON shall be compatible with C++03 or C++11 compliant compilers.
+
+9. Does RapidJSON really work in real applications?
+
+   Yes. It is deployed in both client and server real applications. A community member reported that RapidJSON in their system parses 50 million JSONs daily.
+
+10. How RapidJSON is tested?
+
+   RapidJSON contains a unit test suite for automatic testing. [Travis](https://travis-ci.org/Tencent/rapidjson/)(for Linux) and [AppVeyor](https://ci.appveyor.com/project/Tencent/rapidjson/)(for Windows) will compile and run the unit test suite for all modifications. The test process also uses Valgrind (in Linux) to detect memory leaks.
+
+11. Is RapidJSON well documented?
+
+   RapidJSON provides user guide and API documentationn.
+
+12. Are there alternatives?
+
+   Yes, there are a lot alternatives. For example, [nativejson-benchmark](https://github.com/miloyip/nativejson-benchmark) has a listing of open-source C/C++ JSON libraries. [json.org](http://www.json.org/) also has a list.
+
+## JSON
+
+1. What is JSON?
+
+   JSON (JavaScript Object Notation) is a lightweight data-interchange format. It uses human readable text format. More details of JSON can be referred to [RFC7159](http://www.ietf.org/rfc/rfc7159.txt) and [ECMA-404](http://www.ecma-international.org/publications/standards/Ecma-404.htm).
+
+2. What are applications of JSON?
+
+   JSON are commonly used in web applications for transferring structured data. It is also used as a file format for data persistence.
+
+2. Does RapidJSON conform to the JSON standard?
+
+   Yes. RapidJSON is fully compliance with [RFC7159](http://www.ietf.org/rfc/rfc7159.txt) and [ECMA-404](http://www.ecma-international.org/publications/standards/Ecma-404.htm). It can handle corner cases, such as supporting null character and surrogate pairs in JSON strings.
+
+3. Does RapidJSON support relaxed syntax?
+
+   Currently no. RapidJSON only support the strict standardized format. Support on related syntax is under discussion in this [issue](https://github.com/Tencent/rapidjson/issues/36).
+
+## DOM and SAX
+
+1. What is DOM style API?
+
+   Document Object Model (DOM) is an in-memory representation of JSON for query and manipulation.
+
+2. What is SAX style API?
+
+   SAX is an event-driven API for parsing and generation.
+
+3. Should I choose DOM or SAX?
+
+   DOM is easy for query and manipulation. SAX is very fast and memory-saving but often more difficult to be applied.
+
+4. What is *in situ* parsing?
+
+   *in situ* parsing decodes the JSON strings directly into the input JSON. This is an optimization which can reduce memory consumption and improve performance, but the input JSON will be modified. Check [in-situ parsing](doc/dom.md) for details.
+
+5. When does parsing generate an error?
+
+   The parser generates an error when the input JSON contains invalid syntax, or a value can not be represented (a number is too big), or the handler of parsers terminate the parsing. Check [parse error](doc/dom.md) for details.
+
+6. What error information is provided? 
+
+   The error is stored in `ParseResult`, which includes the error code and offset (number of characters from the beginning of JSON). The error code can be translated into human-readable error message.
+
+7. Why not just using `double` to represent JSON number?
+
+   Some applications use 64-bit unsigned/signed integers. And these integers cannot be converted into `double` without loss of precision. So the parsers detects whether a JSON number is convertible to different types of integers and/or `double`.
+
+8. How to clear-and-minimize a document or value?
+
+   Call one of the `SetXXX()` methods - they call destructor which deallocates DOM data:
+
+   ~~~~~~~~~~cpp
+   Document d;
+   ...
+   d.SetObject();  // clear and minimize
+   ~~~~~~~~~~
+
+   Alternatively, use equivalent of the [C++ swap with temporary idiom](https://en.wikibooks.org/wiki/More_C%2B%2B_Idioms/Clear-and-minimize):
+   ~~~~~~~~~~cpp
+   Value(kObjectType).Swap(d);
+   ~~~~~~~~~~
+   or equivalent, but slightly longer to type:
+   ~~~~~~~~~~cpp
+   d.Swap(Value(kObjectType).Move()); 
+   ~~~~~~~~~~
+
+9. How to insert a document node into another document?
+
+   Let's take the following two DOM trees represented as JSON documents:
+   ~~~~~~~~~~cpp
+   Document person;
+   person.Parse("{\"person\":{\"name\":{\"first\":\"Adam\",\"last\":\"Thomas\"}}}");
+   
+   Document address;
+   address.Parse("{\"address\":{\"city\":\"Moscow\",\"street\":\"Quiet\"}}");
+   ~~~~~~~~~~
+   Let's assume we want to merge them in such way that the whole `address` document becomes a node of the `person`:
+   ~~~~~~~~~~js
+   { "person": {
+      "name": { "first": "Adam", "last": "Thomas" },
+      "address": { "city": "Moscow", "street": "Quiet" }
+      }
+   }
+   ~~~~~~~~~~
+
+   The most important requirement to take care of document and value life-cycle as well as consistent memory management using the right allocator during the value transfer.
+   
+   Simple yet most efficient way to achieve that is to modify the `address` definition above to initialize it with allocator of the `person` document, then we just add the root member of the value:
+   ~~~~~~~~~~cpp
+   Document address(person.GetAllocator());
+   ...
+   person["person"].AddMember("address", address["address"], person.GetAllocator());
+   ~~~~~~~~~~
+Alternatively, if we don't want to explicitly refer to the root value of `address` by name, we can refer to it via iterator:
+   ~~~~~~~~~~cpp
+   auto addressRoot = address.MemberBegin();
+   person["person"].AddMember(addressRoot->name, addressRoot->value, person.GetAllocator());
+   ~~~~~~~~~~
+   
+   Second way is to deep-clone the value from the address document:
+   ~~~~~~~~~~cpp
+   Value addressValue = Value(address["address"], person.GetAllocator());
+   person["person"].AddMember("address", addressValue, person.GetAllocator());
+   ~~~~~~~~~~
+
+## Document/Value (DOM)
+
+1. What is move semantics? Why?
+
+   Instead of copy semantics, move semantics is used in `Value`. That means, when assigning a source value to a target value, the ownership of source value is moved to the target value.
+
+   Since moving is faster than copying, this design decision forces user to aware of the copying overhead.
+
+2. How to copy a value?
+
+   There are two APIs: constructor with allocator, and `CopyFrom()`. See [Deep Copy Value](doc/tutorial.md) for an example.
+
+3. Why do I need to provide the length of string?
+
+   Since C string is null-terminated, the length of string needs to be computed via `strlen()`, with linear runtime complexity. This incurs an unnecessary overhead of many operations, if the user already knows the length of string.
+
+   Also, RapidJSON can handle `\u0000` (null character) within a string. If a string contains null characters, `strlen()` cannot return the true length of it. In such case user must provide the length of string explicitly.
+
+4. Why do I need to provide allocator parameter in many DOM manipulation API?
+
+   Since the APIs are member functions of `Value`, we do not want to save an allocator pointer in every `Value`.
+
+5. Does it convert between numerical types?
+
+   When using `GetInt()`, `GetUint()`, ... conversion may occur. For integer-to-integer conversion, it only convert when it is safe (otherwise it will assert). However, when converting a 64-bit signed/unsigned integer to double, it will convert but be aware that it may lose precision. A number with fraction, or an integer larger than 64-bit, can only be obtained by `GetDouble()`.
+
+## Reader/Writer (SAX)
+
+1. Why don't we just `printf` a JSON? Why do we need a `Writer`? 
+
+   Most importantly, `Writer` will ensure the output JSON is well-formed. Calling SAX events incorrectly (e.g. `StartObject()` pairing with `EndArray()`) will assert. Besides, `Writer` will escapes strings (e.g., `\n`). Finally, the numeric output of `printf()` may not be a valid JSON number, especially in some locale with digit delimiters. And the number-to-string conversion in `Writer` is implemented with very fast algorithms, which outperforms than `printf()` or `iostream`.
+
+2. Can I pause the parsing process and resume it later?
+
+   This is not directly supported in the current version due to performance consideration. However, if the execution environment supports multi-threading, user can parse a JSON in a separate thread, and pause it by blocking in the input stream.
+
+## Unicode
+
+1. Does it support UTF-8, UTF-16 and other format?
+
+   Yes. It fully support UTF-8, UTF-16 (LE/BE), UTF-32 (LE/BE) and ASCII. 
+
+2. Can it validate the encoding?
+
+   Yes, just pass `kParseValidateEncodingFlag` to `Parse()`. If there is invalid encoding in the stream, it will generate `kParseErrorStringInvalidEncoding` error.
+
+3. What is surrogate pair? Does RapidJSON support it?
+
+   JSON uses UTF-16 encoding when escaping unicode character, e.g. `\u5927` representing Chinese character "big". To handle characters other than those in basic multilingual plane (BMP), UTF-16 encodes those characters with two 16-bit values, which is called UTF-16 surrogate pair. For example, the Emoji character U+1F602 can be encoded as `\uD83D\uDE02` in JSON.
+
+   RapidJSON fully support parsing/generating UTF-16 surrogates. 
+
+4. Can it handle `\u0000` (null character) in JSON string?
+
+   Yes. RapidJSON fully support null character in JSON string. However, user need to be aware of it and using `GetStringLength()` and related APIs to obtain the true length of string.
+
+5. Can I output `\uxxxx` for all non-ASCII character?
+
+   Yes, use `ASCII<>` as output encoding template parameter in `Writer` can enforce escaping those characters.
+
+## Stream
+
+1. I have a big JSON file. Should I load the whole file to memory?
+
+   User can use `FileReadStream` to read the file chunk-by-chunk. But for *in situ* parsing, the whole file must be loaded.
+
+2. Can I parse JSON while it is streamed from network?
+
+   Yes. User can implement a custom stream for this. Please refer to the implementation of `FileReadStream`.
+
+3. I don't know what encoding will the JSON be. How to handle them?
+
+   You may use `AutoUTFInputStream` which detects the encoding of input stream automatically. However, it will incur some performance overhead.
+
+4. What is BOM? How RapidJSON handle it?
+
+   [Byte order mark (BOM)](http://en.wikipedia.org/wiki/Byte_order_mark) sometimes reside at the beginning of file/stream to indicate the UTF encoding type of it.
+
+   RapidJSON's `EncodedInputStream` can detect/consume BOM. `EncodedOutputStream` can optionally write a BOM. See [Encoded Streams](doc/stream.md) for example.
+
+5. Why little/big endian is related?
+
+   little/big endian of stream is an issue for UTF-16 and UTF-32 streams, but not UTF-8 stream.
+
+## Performance
+
+1. Is RapidJSON really fast?
+
+   Yes. It may be the fastest open source JSON library. There is a [benchmark](https://github.com/miloyip/nativejson-benchmark) for evaluating performance of C/C++ JSON libraries.
+
+2. Why is it fast?
+
+   Many design decisions of RapidJSON is aimed at time/space performance. These may reduce user-friendliness of APIs. Besides, it also employs low-level optimizations (intrinsics, SIMD) and special algorithms (custom double-to-string, string-to-double conversions).
+
+3. What is SIMD? How it is applied in RapidJSON?
+
+   [SIMD](http://en.wikipedia.org/wiki/SIMD) instructions can perform parallel computation in modern CPUs. RapidJSON support Intel's SSE2/SSE4.2 and ARM's Neon to accelerate whitespace/tabspace/carriage-return/line-feed skipping. This improves performance of parsing indent formatted JSON. Define `RAPIDJSON_SSE2`, `RAPIDJSON_SSE42` or `RAPIDJSON_NEON` macro to enable this feature. However, running the executable on a machine without such instruction set support will make it crash.
+
+4. Does it consume a lot of memory?
+
+   The design of RapidJSON aims at reducing memory footprint.
+
+   In the SAX API, `Reader` consumes memory proportional to maximum depth of JSON tree, plus maximum length of JSON string.
+
+   In the DOM API, each `Value` consumes exactly 16/24 bytes for 32/64-bit architecture respectively. RapidJSON also uses a special memory allocator to minimize overhead of allocations.
+
+5. What is the purpose of being high performance?
+
+   Some applications need to process very large JSON files. Some server-side applications need to process huge amount of JSONs. Being high performance can improve both latency and throughput. In a broad sense, it will also save energy.
+
+## Gossip
+
+1. Who are the developers of RapidJSON?
+
+   Milo Yip ([miloyip](https://github.com/miloyip)) is the original author of RapidJSON. Many contributors from the world have improved RapidJSON.  Philipp A. Hartmann ([pah](https://github.com/pah)) has implemented a lot of improvements, setting up automatic testing and also involves in a lot of discussions for the community. Don Ding ([thebusytypist](https://github.com/thebusytypist)) implemented the iterative parser. Andrii Senkovych ([jollyroger](https://github.com/jollyroger)) completed the CMake migration. Kosta ([Kosta-Github](https://github.com/Kosta-Github)) provided a very neat short-string optimization. Thank you for all other contributors and community members as well.
+
+2. Why do you develop RapidJSON?
+
+   It was just a hobby project initially in 2011. Milo Yip is a game programmer and he just knew about JSON at that time and would like to apply JSON in future projects. As JSON seems very simple he would like to write a header-only and fast library.
+
+3. Why there is a long empty period of development?
+
+   It is basically due to personal issues, such as getting new family members. Also, Milo Yip has spent a lot of spare time on translating "Game Engine Architecture" by Jason Gregory into Chinese.
+
+4. Why did the repository move from Google Code to GitHub?
+
+   This is the trend. And GitHub is much more powerful and convenient.