diff --git a/CHANGELOG.md b/CHANGELOG.md index d1c948a91..0205e7b89 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,9 +4,12 @@ This project adheres to [Semantic Versioning](http://semver.org/). ## [Unreleased] +## 1.1.0 - 2016-08-25 + ### Added * Add GenericDocument ctor overload to specify JSON type (#369) * Add FAQ (#372, #373, #374, #376) +* Add forward declaration header `fwd.h` * Add @PlatformIO Library Registry manifest file (#400) * Implement assignment operator for BigInteger (#404) * Add comments support (#443) @@ -33,11 +36,15 @@ This project adheres to [Semantic Versioning](http://semver.org/). * Add parse-by-parts example (#556, #562) * Support parse number as string (#564, #589) * Add kFormatSingleLineArray for PrettyWriter (#577) -* Added optional support for trailing commas #584 +* Added optional support for trailing commas (#584) +* Added filterkey and filterkeydom examples (#615) +* Added npm docs (#639) +* Allow options for writing and parsing NaN/Infinity (#641) +* Add std::string overload to PrettyWriter::Key() when RAPIDJSON_HAS_STDSTRING is defined (#698) ### Fixed -* Fix gcc/clang/vc warnings (#350, #394, #397, #444, #447, #473, #515, #582, #589, #595) -* Fix documentation (#482, #511, #550, #557) +* Fix gcc/clang/vc warnings (#350, #394, #397, #444, #447, #473, #515, #582, #589, #595, #667) +* Fix documentation (#482, #511, #550, #557, #614, #635, #660) * Fix emscripten alignment issue (#535) * Fix missing allocator to uses of AddMember in document (#365) * CMake will no longer complain that the minimum CMake version is not specified (#501) @@ -56,6 +63,13 @@ This project adheres to [Semantic Versioning](http://semver.org/). * Fix a crash bug in regex (#605) * Fix schema "required" keyword cannot handle duplicated keys (#609) * Fix cmake CMP0054 warning (#612) +* Added missing include guards in istreamwrapper.h and ostreamwrapper.h (#634) +* Fix undefined behaviour (#646) +* Fix buffer overrun using PutN (#673) +* Fix rapidjson::value::Get() may returns wrong data (#681) +* Add Flush() for all value types (#689) +* Handle malloc() fail in PoolAllocator (#691) +* Fix builds on x32 platform. #703 ### Changed * Clarify problematic JSON license (#392) @@ -63,7 +77,9 @@ This project adheres to [Semantic Versioning](http://semver.org/). * Make whitespace array more compact (#513) * Optimize Writer::WriteString() with SIMD (#544) * x86-64 48-bit pointer optimization for GenericValue (#546) - +* Define RAPIDJSON_HAS_CXX11_RVALUE_REFS directly in clang (#617) +* Make GenericSchemaDocument constructor explicit (#674) +* Optimize FindMember when use std::string (#690) ## [1.0.2] - 2015-05-14 @@ -135,7 +151,8 @@ This project adheres to [Semantic Versioning](http://semver.org/). ## 0.1 - 2011-11-18 -[Unreleased]: https://github.com/miloyip/rapidjson/compare/v1.0.2...HEAD +[Unreleased]: https://github.com/miloyip/rapidjson/compare/v1.1.0...HEAD +[1.1.0]: https://github.com/miloyip/rapidjson/compare/v1.0.2...v1.1.0 [1.0.2]: https://github.com/miloyip/rapidjson/compare/v1.0.1...v1.0.2 [1.0.1]: https://github.com/miloyip/rapidjson/compare/v1.0.0...v1.0.1 [1.0.0]: https://github.com/miloyip/rapidjson/compare/v1.0-beta...v1.0.0 diff --git a/CMakeLists.txt b/CMakeLists.txt index 96bfdc2ae..ceda71b1b 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -12,8 +12,8 @@ SET(CMAKE_MODULE_PATH ${CMAKE_CURRENT_SOURCE_DIR}/CMakeModules) PROJECT(RapidJSON CXX) set(LIB_MAJOR_VERSION "1") -set(LIB_MINOR_VERSION "0") -set(LIB_PATCH_VERSION "2") +set(LIB_MINOR_VERSION "1") +set(LIB_PATCH_VERSION "0") set(LIB_VERSION_STRING "${LIB_MAJOR_VERSION}.${LIB_MINOR_VERSION}.${LIB_PATCH_VERSION}") # compile in release with debug info mode by default diff --git a/appveyor.yml b/appveyor.yml index 205c670db..dfedf9c29 100644 --- a/appveyor.yml +++ b/appveyor.yml @@ -1,5 +1,5 @@ os: Visual Studio 2015 CTP -version: 1.0.2.{build} +version: 1.1.0.{build} configuration: - Debug diff --git a/doc/Doxyfile.in b/doc/Doxyfile.in index fcb092660..ca1423396 100644 --- a/doc/Doxyfile.in +++ b/doc/Doxyfile.in @@ -765,6 +765,7 @@ WARN_LOGFILE = # Note: If this tag is empty the current directory is searched. INPUT = readme.md \ + CHANGELOG.md \ include/rapidjson/rapidjson.h \ include/ \ doc/features.md \ diff --git a/doc/Doxyfile.zh-cn.in b/doc/Doxyfile.zh-cn.in index 76d828b5e..87dd8661b 100644 --- a/doc/Doxyfile.zh-cn.in +++ b/doc/Doxyfile.zh-cn.in @@ -765,6 +765,7 @@ WARN_LOGFILE = # Note: If this tag is empty the current directory is searched. INPUT = readme.zh-cn.md \ + CHANGELOG.md \ include/rapidjson/rapidjson.h \ include/ \ doc/features.zh-cn.md \ diff --git a/doc/dom.zh-cn.md b/doc/dom.zh-cn.md index 13e8c200d..d93f6036b 100644 --- a/doc/dom.zh-cn.md +++ b/doc/dom.zh-cn.md @@ -1,6 +1,6 @@ # DOM -文档对象模型(Document Object Model, DOM)是一种罝于内存中的 JSON 表示方式,以供查询及操作。我们己于 [教程](doc/tutorial.md) 中介绍了 DOM 的基本用法,本节将讲述一些细节及高级用法。 +文档对象模型(Document Object Model, DOM)是一种罝于内存中的 JSON 表示方式,以供查询及操作。我们己于 [教程](doc/tutorial.zh-cn.md) 中介绍了 DOM 的基本用法,本节将讲述一些细节及高级用法。 [TOC] @@ -31,7 +31,7 @@ typedef GenericDocument > Document; ## 编码 {#Encoding} -`Encoding` 参数指明在内存中的 JSON String 使用哪种编码。可行的选项有 `UTF8`、`UTF16`、`UTF32`。要注意这 3 个类型其实也是模板类。`UTF8<>` 等同 `UTF8`,这代表它使用 `char` 来存储字符串。更多细节可以参考 [编码](encoding.md)。 +`Encoding` 参数指明在内存中的 JSON String 使用哪种编码。可行的选项有 `UTF8`、`UTF16`、`UTF32`。要注意这 3 个类型其实也是模板类。`UTF8<>` 等同 `UTF8`,这代表它使用 `char` 来存储字符串。更多细节可以参考 [编码](doc/encoding.zh-cn.md)。 这里是一个例子。假设一个 Windows 应用软件希望查询存储于 JSON 中的本地化字符串。Windows 中含 Unicode 的函数使用 UTF-16(宽字符)编码。无论 JSON 文件使用哪种编码,我们都可以把字符串以 UTF-16 形式存储在内存。 @@ -102,7 +102,7 @@ GenericDocument& GenericDocument::Parse(const Ch* str); GenericDocument& GenericDocument::Parse(const Ch* str); ~~~~~~~~~~ -[教程](tutorial.md) 中的例使用 (8) 去正常解析字符串。而 [流](stream.md) 的例子使用前 3 个函数。我们将稍后介绍原位(*In situ*) 解析。 +[教程](doc/tutorial.zh-cn.md) 中的例使用 (8) 去正常解析字符串。而 [流](doc/stream.zh-cn.md) 的例子使用前 3 个函数。我们将稍后介绍原位(*In situ*) 解析。 `parseFlags` 是以下位标置的组合: @@ -118,6 +118,7 @@ GenericDocument& GenericDocument::Parse(const Ch* str); `kParseCommentsFlag` | 容许单行 `// ...` 及多行 `/* ... */` 注释(放宽的 JSON 语法)。 `kParseNumbersAsStringsFlag` | 把数字类型解析成字符串。 `kParseTrailingCommasFlag` | 容许在对象和数组结束前含有逗号(放宽的 JSON 语法)。 +`kParseNanAndInfFlag` | 容许 `NaN`、`Inf`、`Infinity`、`-Inf` 及 `-Infinity` 作为 `double` 值(放宽的 JSON 语法)。 由于使用了非类型模板参数,而不是函数参数,C++ 编译器能为个别组合生成代码,以改善性能及减少代码尺寸(当只用单种特化)。缺点是需要在编译期决定标志。 @@ -230,9 +231,9 @@ JSON string 会被打上 const-string 的标志。但它们可能并非真正的 ## 转码与校验 {#TranscodingAndValidation} -RapidJSON 内部支持不同 Unicode 格式(正式的术语是 UCS 变换格式)间的转换。在 DOM 解析时,流的来源编码与 DOM 的编码可以不同。例如,来源流可能含有 UTF-8 的 JSON,而 DOM 则使用 UTF-16 编码。在 [EncodedInputStream](doc/stream.md) 一节里有一个例子。 +RapidJSON 内部支持不同 Unicode 格式(正式的术语是 UCS 变换格式)间的转换。在 DOM 解析时,流的来源编码与 DOM 的编码可以不同。例如,来源流可能含有 UTF-8 的 JSON,而 DOM 则使用 UTF-16 编码。在 [EncodedInputStream](doc/stream.zh-cn.md) 一节里有一个例子。 -当从 DOM 输出一个 JSON 至输出流之时,也可以使用转码功能。在 [EncodedOutputStream](doc/stream.md) 一节里有一个例子。 +当从 DOM 输出一个 JSON 至输出流之时,也可以使用转码功能。在 [EncodedOutputStream](doc/stream.zh-cn.md) 一节里有一个例子。 在转码过程中,会把来源 string 解码成 Unicode 码点,然后把码点编码成目标格式。在解码时,它会校验来源 string 的字节序列是否合法。若遇上非合法序列,解析器会停止并返回 `kParseErrorStringInvalidEncoding` 错误。 @@ -256,9 +257,9 @@ d.Accept(writer); 使用者可以创建自定义的处理器,去把 DOM 转换成其它格式。例如,一个把 DOM 转换成 XML 的处理器。 -要知道更多关于 SAX 事件与处理器,可参阅 [SAX](doc/sax.md)。 +要知道更多关于 SAX 事件与处理器,可参阅 [SAX](doc/sax.zh-cn.md)。 -## 使用者缓冲区{ #UserBuffer} +## 使用者缓冲区 {#UserBuffer} 许多应用软件可能需要尽量减少内存分配。 diff --git a/doc/encoding.zh-cn.md b/doc/encoding.zh-cn.md index 163eadec5..681692355 100644 --- a/doc/encoding.zh-cn.md +++ b/doc/encoding.zh-cn.md @@ -79,7 +79,7 @@ typedef GenericDocument > WDocument; typedef GenericValue > WValue; ~~~~~~~~~~ -可以在 [DOM's Encoding](doc/stream.md) 一节看到更详细的使用例子。 +可以在 [DOM's Encoding](doc/stream.zh-cn.md) 一节看到更详细的使用例子。 ## 字符类型 {#CharacterType} diff --git a/doc/faq.zh-cn.md b/doc/faq.zh-cn.md index cc985e707..ed100e112 100644 --- a/doc/faq.zh-cn.md +++ b/doc/faq.zh-cn.md @@ -88,11 +88,11 @@ 4. 什么是原位(*in situ*)解析? - 原位解析会把 JSON 字符串直接解码至输入的 JSON 中。这是一个优化,可减少内存消耗及提升性能,但输入的 JSON 会被更改。进一步细节请参考 [原位解析](doc/dom.md) 。 + 原位解析会把 JSON 字符串直接解码至输入的 JSON 中。这是一个优化,可减少内存消耗及提升性能,但输入的 JSON 会被更改。进一步细节请参考 [原位解析](doc/dom.zh-cn.md) 。 5. 什么时候会产生解析错误? - 当输入的 JSON 包含非法语法,或不能表示一个值(如 Number 太大),或解析器的处理器中断解析过程,解析器都会产生一个错误。详情请参考 [解析错误](doc/dom.md)。 + 当输入的 JSON 包含非法语法,或不能表示一个值(如 Number 太大),或解析器的处理器中断解析过程,解析器都会产生一个错误。详情请参考 [解析错误](doc/dom.zh-cn.md)。 6. 有什么错误信息? @@ -171,7 +171,7 @@ 2. 怎样去复制一个值? - 有两个 API 可用:含 allocator 的构造函数,以及 `CopyFrom()`。可参考 [深复制 Value](doc/tutorial.md) 里的用例。 + 有两个 API 可用:含 allocator 的构造函数,以及 `CopyFrom()`。可参考 [深复制 Value](doc/tutorial.zh-cn.md) 里的用例。 3. 为什么我需要提供字符串的长度? @@ -239,7 +239,7 @@ [字节顺序标记(byte order mark, BOM)](http://en.wikipedia.org/wiki/Byte_order_mark) 有时会出现于文件/流的开始,以表示其 UTF 编码类型。 - RapidJSON 的 `EncodedInputStream` 可检测/跳过 BOM。`EncodedOutputStream` 可选择是否写入 BOM。可参考 [编码流](doc/stream.md) 中的例子。 + RapidJSON 的 `EncodedInputStream` 可检测/跳过 BOM。`EncodedOutputStream` 可选择是否写入 BOM。可参考 [编码流](doc/stream.zh-cn.md) 中的例子。 5. 为什么会涉及大端/小端? diff --git a/doc/features.md b/doc/features.md index 984c6abae..732fb21f4 100644 --- a/doc/features.md +++ b/doc/features.md @@ -20,13 +20,16 @@ ## Standard compliance * RapidJSON should be fully RFC4627/ECMA-404 compliance. +* Support JSON Pointer (RFC6901). +* Support JSON Schema Draft v4. * Support Unicode surrogate. * Support null character (`"\u0000"`) * For example, `["Hello\u0000World"]` can be parsed and handled gracefully. There is API for getting/setting lengths of string. * Support optional relaxed syntax. * Single line (`// ...`) and multiple line (`/* ... */`) comments (`kParseCommentsFlag`). * Trailing commas at the end of objects and arrays (`kParseTrailingCommasFlag`). -* [NPM compliant](doc/npm.md). + * `NaN`, `Inf`, `Infinity`, `-Inf` and `-Infinity` as `double` values (`kParseNanAndInfFlag`) +* [NPM compliant](http://github.com/miloyip/rapidjson/blob/master/doc/npm.md). ## Unicode @@ -70,7 +73,7 @@ * Only store pointer instead of copying * Optimization for "short" strings * Store short string in `Value` internally without additional allocation. - * For UTF-8 string: maximum 11 characters in 32-bit, 15 characters in 64-bit. + * For UTF-8 string: maximum 11 characters in 32-bit, 21 characters in 64-bit (13 characters in x86-64). * Optionally support `std::string` (define `RAPIDJSON_HAS_STDSTRING=1`) ## Generation @@ -98,3 +101,4 @@ * Some C++11 support (optional) * Rvalue reference * `noexcept` specifier + * Range-based for loop diff --git a/doc/features.zh-cn.md b/doc/features.zh-cn.md index 623cf6203..fd3fd4d66 100644 --- a/doc/features.zh-cn.md +++ b/doc/features.zh-cn.md @@ -20,12 +20,16 @@ ## 符合标准 * RapidJSON 应完全符合 RFC4627/ECMA-404 标准。 +* 支持 JSON Pointer (RFC6901). +* 支持 JSON Schema Draft v4. * 支持 Unicod 代理对(surrogate pair)。 * 支持空字符(`"\u0000"`)。 * 例如,可以优雅地解析及处理 `["Hello\u0000World"]`。含读写字符串长度的 API。 -* 支持放宽的可选语法 +* 支持可选的放宽语法 * 单行(`// ...`)及多行(`/* ... */`) 注释 (`kParseCommentsFlag`)。 * 在对象和数组结束前含逗号 (`kParseTrailingCommasFlag`)。 + * `NaN`、`Inf`、`Infinity`、`-Inf` 及 `-Infinity` 作为 `double` 值 (`kParseNanAndInfFlag`) +* [NPM 兼容](https://github.com/miloyip/rapidjson/blob/master/doc/npm.md). ## Unicode @@ -68,7 +72,7 @@ * 只储存指针,不作复制 * 优化“短”字符串 * 在 `Value` 内储存短字符串,无需额外分配。 - * 对 UTF-8 字符串来说,32 位架构下可存储最多 11 字符,64 位下 15 字符。 + * 对 UTF-8 字符串来说,32 位架构下可存储最多 11 字符,64 位下 21 字符(x86-64 下 13 字符)。 * 可选地支持 `std::string`(定义 `RAPIDJSON_HAS_STDSTRING=1`) ## 生成 @@ -96,3 +100,4 @@ * 一些 C++11 的支持(可选) * 右值引用(rvalue reference) * `noexcept` 修饰符 + * 范围 for 循环 diff --git a/doc/internals.md b/doc/internals.md index 174a03a24..49802a0fd 100644 --- a/doc/internals.md +++ b/doc/internals.md @@ -114,7 +114,7 @@ Number is a bit more complicated. For normal integer values, it can contains `kI ## Short-String Optimization {#ShortString} - Kosta (@Kosta-Github) provided a very neat short-string optimization. The optimization idea is given as follow. Excluding the `flags_`, a `Value` has 12 or 16 bytes (32-bit or 64-bit) for storing actual data. Instead of storing a pointer to a string, it is possible to store short strings in these space internally. For encoding with 1-byte character type (e.g. `char`), it can store maximum 11 or 15 characters string inside the `Value` type. + [Kosta](https://github.com/Kosta-Github) provided a very neat short-string optimization. The optimization idea is given as follow. Excluding the `flags_`, a `Value` has 12 or 16 bytes (32-bit or 64-bit) for storing actual data. Instead of storing a pointer to a string, it is possible to store short strings in these space internally. For encoding with 1-byte character type (e.g. `char`), it can store maximum 11 or 15 characters string inside the `Value` type. | ShortString (Ch=char) | |32-bit|64-bit| |---------------------|-------------------------------------|:----:|:----:| @@ -126,7 +126,7 @@ A special technique is applied. Instead of storing the length of string directly This optimization can reduce memory usage for copy-string. It can also improve cache-coherence thus improve runtime performance. -# Allocator {#Allocator} +# Allocator {#InternalAllocator} `Allocator` is a concept in RapidJSON: ~~~cpp @@ -158,7 +158,7 @@ Note that `Malloc()` and `Realloc()` are member functions but `Free()` is static Internally, it allocates chunks of memory from the base allocator (by default `CrtAllocator`) and stores the chunks as a singly linked list. When user requests an allocation, it allocates memory from the following order: -1. User supplied buffer if it is available. (See [User Buffer section in DOM](dom.md)) +1. User supplied buffer if it is available. (See [User Buffer section in DOM](doc/dom.md)) 2. If user supplied buffer is full, use the current memory chunk. 3. If the current block is full, allocate a new block of memory. diff --git a/doc/performance.md b/doc/performance.md index 702ca7230..988e799e9 100644 --- a/doc/performance.md +++ b/doc/performance.md @@ -1,6 +1,6 @@ # Performance -There is a [native JSON benchmark collection] [1] which evaluates speed, memory usage and code size of various operations among 20 JSON libaries. +There is a [native JSON benchmark collection] [1] which evaluates speed, memory usage and code size of various operations among 37 JSON libaries. [1]: https://github.com/miloyip/nativejson-benchmark diff --git a/doc/performance.zh-cn.md b/doc/performance.zh-cn.md index da5d0c67f..c20c5050f 100644 --- a/doc/performance.zh-cn.md +++ b/doc/performance.zh-cn.md @@ -1,6 +1,6 @@ # 性能 -有一个 [native JSON benchmark collection][1] 项目,能评估 20 个 JSON 库在不同操作下的速度、內存用量及代码大小。 +有一个 [native JSON benchmark collection][1] 项目,能评估 37 个 JSON 库在不同操作下的速度、內存用量及代码大小。 [1]: https://github.com/miloyip/nativejson-benchmark diff --git a/doc/pointer.md b/doc/pointer.md index 3927a12ec..b343d78ed 100644 --- a/doc/pointer.md +++ b/doc/pointer.md @@ -1,6 +1,6 @@ # Pointer -## Status: experimental, shall be included in v1.1 +(This feature was released in v1.1.0) JSON Pointer is a standardized ([RFC6901]) way to select a value inside a JSON Document (DOM). This can be analogous to XPath for XML document. However, JSON Pointer is much simpler, and a single JSON Pointer only pointed to a single value. diff --git a/doc/pointer.zh-cn.md b/doc/pointer.zh-cn.md index d9bd9c3cb..f58f55f3d 100644 --- a/doc/pointer.zh-cn.md +++ b/doc/pointer.zh-cn.md @@ -1,6 +1,6 @@ # Pointer -## 状态: 实验性,应该会合进 v1.1 +(本功能于 v1.1.0 发布) JSON Pointer 是一个标准化([RFC6901])的方式去选取一个 JSON Document(DOM)中的值。这类似于 XML 的 XPath。然而,JSON Pointer 简单得多,而且每个 JSON Pointer 仅指向单个值。 diff --git a/doc/sax.md b/doc/sax.md index 5b36d0557..1d4fc2ae5 100644 --- a/doc/sax.md +++ b/doc/sax.md @@ -159,7 +159,7 @@ Note that, the default character type of `UTF16` is `wchar_t`. So this `reader`n The third template parameter `Allocator` is the allocator type for internal data structure (actually a stack). -## Parsing {#Parsing} +## Parsing {#SaxParsing} The one and only one function of `Reader` is to parse JSON. @@ -244,7 +244,7 @@ Anyway, using `Writer` API is even simpler than generating a JSON by ad hoc meth ~~~~~~~~~~cpp namespace rapidjson { -template, typename TargetEncoding = UTF8<>, typename Allocator = CrtAllocator<> > +template, typename TargetEncoding = UTF8<>, typename Allocator = CrtAllocator<>, unsigned writeFlags = kWriteDefaultFlags> class Writer { public: Writer(OutputStream& os, Allocator* allocator = 0, size_t levelDepth = kDefaultLevelDepth) @@ -260,7 +260,16 @@ The `SourceEncoding` template parameter specifies the encoding to be used in `St The `TargetEncoding` template parameter specifies the encoding in the output stream. -The last one, `Allocator` is the type of allocator, which is used for allocating internal data structure (a stack). +The `Allocator` is the type of allocator, which is used for allocating internal data structure (a stack). + +The `writeFlags` are combination of the following bit-flags: + +Parse flags | Meaning +------------------------------|----------------------------------- +`kWriteNoFlags` | No flag is set. +`kWriteDefaultFlags` | Default write flags. It is equal to macro `RAPIDJSON_WRITE_DEFAULT_FLAGS`, which is defined as `kWriteNoFlags`. +`kWriteValidateEncodingFlag` | Validate encoding of JSON strings. +`kWriteNanAndInfFlag` | Allow writing of `Infinity`, `-Infinity` and `NaN`. Besides, the constructor of `Writer` has a `levelDepth` parameter. This parameter affects the initial memory allocated for storing information per hierarchy level. @@ -278,7 +287,7 @@ A `Writer` can only output a single JSON, which can be any JSON type at the root When a JSON is complete, the `Writer` cannot accept any new events. Otherwise the output will be invalid (i.e. having more than one root). To reuse the `Writer` object, user can call `Writer::Reset(OutputStream& os)` to reset all internal states of the `Writer` with a new output stream. -# Techniques {#Techniques} +# Techniques {#SaxTechniques} ## Parsing JSON to Custom Data Structure {#CustomDataStructure} diff --git a/doc/sax.zh-cn.md b/doc/sax.zh-cn.md index 7b8aabe43..b20286de9 100644 --- a/doc/sax.zh-cn.md +++ b/doc/sax.zh-cn.md @@ -159,7 +159,7 @@ GenericReader, UTF16<> > reader; 第三个模板参数 `Allocator` 是内部数据结构(实际上是一个堆栈)的分配器类型。 -## 解析 {#Parsing} +## 解析 {#SaxParsing} `Reader` 的唯一功能就是解析 JSON。 @@ -172,7 +172,7 @@ template bool Parse(InputStream& is, Handler& handler); ~~~~~~~~~~ -若在解析中出现错误,它会返回 `false`。使用者可调用 `bool HasParseEror()`, `ParseErrorCode GetParseErrorCode()` 及 `size_t GetErrorOffset()` 获取错误状态。实际上 `Document` 使用这些 `Reader` 函数去获取解析错误。请参考 [DOM](doc/dom.md) 去了解有关解析错误的细节。 +若在解析中出现错误,它会返回 `false`。使用者可调用 `bool HasParseEror()`, `ParseErrorCode GetParseErrorCode()` 及 `size_t GetErrorOffset()` 获取错误状态。实际上 `Document` 使用这些 `Reader` 函数去获取解析错误。请参考 [DOM](doc/dom.zh-cn.md) 去了解有关解析错误的细节。 # Writer {#Writer} @@ -260,7 +260,16 @@ public: `TargetEncoding` 模板参数指定输出流的编码。 -最后一个 `Allocator` 是分配器的类型,用于分配内部数据结构(一个堆栈)。 +`Allocator` 是分配器的类型,用于分配内部数据结构(一个堆栈)。 + +`writeFlags` 是以下位标志的组合: + +写入位标志 | 意义 +------------------------------|----------------------------------- +`kWriteNoFlags` | 没有任何标志。 +`kWriteDefaultFlags` | 缺省的解析选项。它等于 `RAPIDJSON_WRITE_DEFAULT_FLAGS` 宏,此宏定义为 `kWriteNoFlags`。 +`kWriteValidateEncodingFlag` | 校验 JSON 字符串的编码。 +`kWriteNanAndInfFlag` | 容许写入 `Infinity`, `-Infinity` 及 `NaN`。 此外,`Writer` 的构造函数有一 `levelDepth` 参数。存储每层阶信息的初始内存分配量受此参数影响。 @@ -278,7 +287,7 @@ public: 当 JSON 完整时,`Writer` 不能再接受新的事件。不然其输出便会是不合法的(例如有超过一个根节点)。为了重新利用 `Writer` 对象,使用者可调用 `Writer::Reset(OutputStream& os)` 去重置其所有内部状态及设置新的输出流。 -# 技巧 {#Techniques} +# 技巧 {#SaxTechniques} ## 解析 JSON 至自定义结构 {#CustomDataStructure} diff --git a/doc/schema.md b/doc/schema.md index 1fad5fbce..a83cebcae 100644 --- a/doc/schema.md +++ b/doc/schema.md @@ -1,6 +1,6 @@ # Schema -## Status: experimental, shall be included in v1.1 +(This feature was released in v1.1.0) JSON Schema is a draft standard for describing the format of JSON data. The schema itself is also JSON data. By validating a JSON structure with JSON Schema, your code can safely access the DOM without manually checking types, or whether a key exists, etc. It can also ensure that the serialized JSON conform to a specified schema. @@ -146,7 +146,7 @@ Of course, if your application only needs SAX-style serialization, it can simply ## Remote Schema -JSON Schema supports [`$ref` keyword](http://spacetelescope.github.io/understanding-json-schema/structuring.html), which is a [JSON pointer](pointer.md) referencing to a local or remote schema. Local pointer is prefixed with `#`, while remote pointer is an relative or absolute URI. For example: +JSON Schema supports [`$ref` keyword](http://spacetelescope.github.io/understanding-json-schema/structuring.html), which is a [JSON pointer](doc/pointer.md) referencing to a local or remote schema. Local pointer is prefixed with `#`, while remote pointer is an relative or absolute URI. For example: ~~~js { "$ref": "definitions.json#/address" } diff --git a/doc/schema.zh-cn.md b/doc/schema.zh-cn.md index 345b7c54f..a01c1b10e 100644 --- a/doc/schema.zh-cn.md +++ b/doc/schema.zh-cn.md @@ -1,6 +1,6 @@ # Schema -## 状态: 实验性,应该会合进 v1.1 +(本功能于 v1.1.0 发布) JSON Schema 是描述 JSON 格式的一个标准草案。一个 schema 本身也是一个 JSON。使用 JSON Schema 去校验 JSON,可以让你的代码安全地访问 DOM,而无须检查类型或键值是否存在等。这也能确保输出的 JSON 是符合指定的 schema。 @@ -146,7 +146,7 @@ if (!d.Accept(validator)) { ## 远程 Schema -JSON Schema 支持 [`$ref` 关键字](http://spacetelescope.github.io/understanding-json-schema/structuring.html),它是一个 [JSON pointer](pointer.md) 引用至一个本地(local)或远程(remote) schema。本地指针的首字符是 `#`,而远程指针是一个相对或绝对 URI。例如: +JSON Schema 支持 [`$ref` 关键字](http://spacetelescope.github.io/understanding-json-schema/structuring.html),它是一个 [JSON pointer](doc/pointer.zh-cn.md) 引用至一个本地(local)或远程(remote) schema。本地指针的首字符是 `#`,而远程指针是一个相对或绝对 URI。例如: ~~~js { "$ref": "definitions.json#/address" } diff --git a/doc/tutorial.md b/doc/tutorial.md index 0da07dc5d..cb76b4b0b 100644 --- a/doc/tutorial.md +++ b/doc/tutorial.md @@ -133,6 +133,15 @@ And other familiar query functions: * `SizeType Capacity() const` * `bool Empty() const` +### Range-based For Loop (New in v1.1.0) + +When C++11 is enabled, you can use range-based for loop to access all elements in an array. + +~~~~~~~~~~cpp +for (auto& v : a.GetArray()) + printf("%d ", v.GetInt()); +~~~~~~~~~~ + ## Query Object {#QueryObject} Similar to array, we can access all object members by iterator: @@ -169,6 +178,16 @@ if (itr != document.MemberEnd()) printf("%s\n", itr->value.GetString()); ~~~~~~~~~~ +### Range-based For Loop (New in v1.1.0) + +When C++11 is enabled, you can use range-based for loop to access all members in an object. + +~~~~~~~~~~cpp +for (auto& m : document.GetObject()) + printf("Type of member %s is %s\n", + m.name.GetString(), kTypeNames[m.value.GetType()]); +~~~~~~~~~~ + ## Querying Number {#QueryNumber} JSON provide a single numerical type called Number. Number can be integer or real numbers. RFC 4627 says the range of Number is specified by parser. diff --git a/doc/tutorial.zh-cn.md b/doc/tutorial.zh-cn.md index f5db1ca6f..61fb0b243 100644 --- a/doc/tutorial.zh-cn.md +++ b/doc/tutorial.zh-cn.md @@ -133,6 +133,15 @@ for (Value::ConstValueIterator itr = a.Begin(); itr != a.End(); ++itr) * `SizeType Capacity() const` * `bool Empty() const` +### 范围 for 循环 (v1.1.0 中的新功能) + +当使用 C++11 功能时,你可使用范围 for 循环去访问 Array 内的所有元素。 + +~~~~~~~~~~cpp +for (auto& v : a.GetArray()) + printf("%d ", v.GetInt()); +~~~~~~~~~~ + ## 查询 Object {#QueryObject} 和 Array 相似,我们可以用迭代器去访问所有 Object 成员: @@ -169,6 +178,16 @@ if (itr != document.MemberEnd()) printf("%s\n", itr->value.GetString()); ~~~~~~~~~~ +### 范围 for 循环 (v1.1.0 中的新功能) + +当使用 C++11 功能时,你可使用范围 for 循环去访问 Object 内的所有成员。 + +~~~~~~~~~~cpp +for (auto& m : document.GetObject()) + printf("Type of member %s is %s\n", + m.name.GetString(), kTypeNames[m.value.GetType()]); +~~~~~~~~~~ + ## 查询 Number {#QueryNumber} JSON 只提供一种数值类型──Number。数字可以是整数或实数。RFC 4627 规定数字的范围由解析器指定。 @@ -510,6 +529,6 @@ assert(b.IsInt()); 3. [DOM](doc/dom.zh-cn.md) 的基本功能已在本教程里介绍。还有更高级的功能,如原位(*in situ*)解析、其他解析选项及高级用法。 4. [SAX](doc/sax.zh-cn.md) 是 RapidJSON 解析/生成功能的基础。学习使用 `Reader`/`Writer` 去实现更高性能的应用程序。也可以使用 `PrettyWriter` 去格式化 JSON。 5. [性能](doc/performance.zh-cn.md) 展示一些我们做的及第三方的性能测试。 -6. [技术内幕](doc/internals.zh-cn.md) 讲述一些 RapidJSON 内部的设计及技术。 +6. [技术内幕](doc/internals.md) 讲述一些 RapidJSON 内部的设计及技术。 -你也可以参考 [常见问题](faq.zh-cn.md)、API 文档、例子及单元测试。 +你也可以参考 [常见问题](doc/faq.zh-cn.md)、API 文档、例子及单元测试。 diff --git a/include/rapidjson/rapidjson.h b/include/rapidjson/rapidjson.h index 4bdaed611..053b2ce43 100644 --- a/include/rapidjson/rapidjson.h +++ b/include/rapidjson/rapidjson.h @@ -68,8 +68,8 @@ \brief Version of RapidJSON in ".." string format. */ #define RAPIDJSON_MAJOR_VERSION 1 -#define RAPIDJSON_MINOR_VERSION 0 -#define RAPIDJSON_PATCH_VERSION 2 +#define RAPIDJSON_MINOR_VERSION 1 +#define RAPIDJSON_PATCH_VERSION 0 #define RAPIDJSON_VERSION_STRING \ RAPIDJSON_STRINGIFY(RAPIDJSON_MAJOR_VERSION.RAPIDJSON_MINOR_VERSION.RAPIDJSON_PATCH_VERSION) diff --git a/include/rapidjson/writer.h b/include/rapidjson/writer.h index 112d767ef..94f22dd5f 100644 --- a/include/rapidjson/writer.h +++ b/include/rapidjson/writer.h @@ -63,7 +63,7 @@ RAPIDJSON_NAMESPACE_BEGIN enum WriteFlag { kWriteNoFlags = 0, //!< No flags are set. kWriteValidateEncodingFlag = 1, //!< Validate encoding of JSON strings. - kWriteNanAndInfFlag = 2, //!< Allow writing of Inf, -Inf and NaN. + kWriteNanAndInfFlag = 2, //!< Allow writing of Infinity, -Infinity and NaN. kWriteDefaultFlags = RAPIDJSON_WRITE_DEFAULT_FLAGS //!< Default write flags. Can be customized by defining RAPIDJSON_WRITE_DEFAULT_FLAGS }; diff --git a/rapidjson.autopkg b/rapidjson.autopkg index d91aaeff6..70eb0d8a0 100644 --- a/rapidjson.autopkg +++ b/rapidjson.autopkg @@ -1,11 +1,11 @@ nuget { - //Usage: Write-NuGetPackage rapidjson.autopkg -defines:MYVERSION=1.0.2 + //Usage: Write-NuGetPackage rapidjson.autopkg -defines:MYVERSION=1.1.0 //Be sure you are running Powershell 3.0 and have the CoApp powershell extensions installed properly. nuspec { id = rapidjson; version : ${MYVERSION}; title: "rapidjson"; - authors: {"https://github.com/miloyip/rapidjson/releases/tag/v1.0.2"}; + authors: {"https://github.com/miloyip/rapidjson/releases/tag/v1.1.0"}; owners: {"@lsantos (github)"}; licenseUrl: "https://github.com/miloyip/rapidjson/blob/master/license.txt"; projectUrl: "https://github.com/miloyip/rapidjson/"; diff --git a/readme.md b/readme.md index fd5d4c6c8..4a1d64d0a 100644 --- a/readme.md +++ b/readme.md @@ -1,6 +1,6 @@ ![](doc/logo/rapidjson.png) -![](https://img.shields.io/badge/release-v1.0.2-blue.png) +![](https://img.shields.io/badge/release-v1.1.0-blue.png) ## A fast JSON parser/generator for C++ with both SAX/DOM style API @@ -37,17 +37,27 @@ RapidJSON is a JSON parser and generator for C++. It was inspired by [RapidXml]( * RapidJSON is **self-contained** and **header-only**. It does not depend on external libraries such as BOOST. It even does not depend on STL. -* RapidJSON is **memory-friendly**. Each JSON value occupies exactly 16/20 bytes for most 32/64-bit machines (excluding text string). By default it uses a fast memory allocator, and the parser allocates memory compactly during parsing. +* RapidJSON is **memory-friendly**. Each JSON value occupies exactly 16 bytes for most 32/64-bit machines (excluding text string). By default it uses a fast memory allocator, and the parser allocates memory compactly during parsing. * RapidJSON is **Unicode-friendly**. It supports UTF-8, UTF-16, UTF-32 (LE & BE), and their detection, validation and transcoding internally. For example, you can read a UTF-8 file and let RapidJSON transcode the JSON strings into UTF-16 in the DOM. It also supports surrogates and "\u0000" (null character). More features can be read [here](doc/features.md). -JSON(JavaScript Object Notation) is a light-weight data exchange format. RapidJSON should be in fully compliance with RFC7159/ECMA-404. More information about JSON can be obtained at +JSON(JavaScript Object Notation) is a light-weight data exchange format. RapidJSON should be in fully compliance with RFC7159/ECMA-404, with optional support of relaxed syntax. More information about JSON can be obtained at * [Introducing JSON](http://json.org/) * [RFC7159: The JavaScript Object Notation (JSON) Data Interchange Format](http://www.ietf.org/rfc/rfc7159.txt) * [Standard ECMA-404: The JSON Data Interchange Format](http://www.ecma-international.org/publications/standards/Ecma-404.htm) +## Highlights in v1.1 (2016-8-25) + +* Added [JSON Pointer](doc/pointer.md) +* Added [JSON Schema](doc/schema.md) +* Added [relaxed JSON syntax](doc/dom.md) (comment, trailing comma, NaN/Infinity) +* Iterating array/object with [C++11 Range-based for loop](doc/tutorial.md) +* Reduce memory overhead of each `Value` from 24 bytes to 16 bytes in x86-64 architecture. + +For other changes please refer to [change log](CHANGELOG.md). + ## Compatibility RapidJSON is cross-platform. Some platform/compiler combinations which have been tested are shown as follows. diff --git a/readme.zh-cn.md b/readme.zh-cn.md index 97101d12b..74d267c98 100644 --- a/readme.zh-cn.md +++ b/readme.zh-cn.md @@ -1,6 +1,6 @@ ![](doc/logo/rapidjson.png) -![](https://img.shields.io/badge/release-v1.0.2-blue.png) +![](https://img.shields.io/badge/release-v1.1.0-blue.png) ## 高效的 C++ JSON 解析/生成器,提供 SAX 及 DOM 风格 API @@ -37,17 +37,27 @@ RapidJSON 是一个 C++ 的 JSON 解析器及生成器。它的灵感来自 [Rap * RapidJSON 独立。它不依赖于 BOOST 等外部库。它甚至不依赖于 STL。 -* RapidJSON 对内存友好。在大部分 32/64 位机器上,每个 JSON 值只占 16 或 20 字节(除字符串外)。它预设使用一个快速的内存分配器,令分析器可以紧凑地分配内存。 +* RapidJSON 对内存友好。在大部分 32/64 位机器上,每个 JSON 值只占 16 字节(除字符串外)。它预设使用一个快速的内存分配器,令分析器可以紧凑地分配内存。 * RapidJSON 对 Unicode 友好。它支持 UTF-8、UTF-16、UTF-32 (大端序/小端序),并内部支持这些编码的检测、校验及转码。例如,RapidJSON 可以在分析一个 UTF-8 文件至 DOM 时,把当中的 JSON 字符串转码至 UTF-16。它也支持代理对(surrogate pair)及 `"\u0000"`(空字符)。 -在 [这里](doc/features.md) 可读取更多特点。 +在 [这里](doc/features.zh-cn.md) 可读取更多特点。 -JSON(JavaScript Object Notation)是一个轻量的数据交换格式。RapidJSON 应该完全遵从 RFC7159/ECMA-404。 关于 JSON 的更多信息可参考: +JSON(JavaScript Object Notation)是一个轻量的数据交换格式。RapidJSON 应该完全遵从 RFC7159/ECMA-404,并支持可选的放宽语法。 关于 JSON 的更多信息可参考: * [Introducing JSON](http://json.org/) * [RFC7159: The JavaScript Object Notation (JSON) Data Interchange Format](http://www.ietf.org/rfc/rfc7159.txt) * [Standard ECMA-404: The JSON Data Interchange Format](http://www.ecma-international.org/publications/standards/Ecma-404.htm) +## v1.1 中的亮点 (2016-8-25) + +* 加入 [JSON Pointer](doc/pointer.zh-cn.md) 功能,可更简单地访问及更改 DOM。 +* 加入 [JSON Schema](doc/schema.zh-cn.md) 功能,可在解析或生成 JSON 时进行校验。 +* 加入 [放宽的 JSON 语法](doc/dom.zh-cn.md) (注释、尾随逗号、NaN/Infinity) +* 使用 [C++11 范围 for 循环](doc/tutorial.zh-cn.md) 去遍历 array 和 object。 +* 在 x86-64 架构下,缩减每个 `Value` 的内存开销从 24 字节至 16 字节。 + +其他改动请参考 [change log](CHANGELOG.md). + ## 兼容性 RapidJSON 是跨平台的。以下是一些曾测试的平台/编译器组合: