@eosrio/node-abieos 2.1.0-beta.0 → 2.2.0

package/external/rapidjson/doc/pointer.md

@@ -1,234 +0,0 @@
-# Pointer
-
-(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.
-
-Using RapidJSON's implementation of JSON Pointer can simplify some manipulations of the DOM.
-
-[TOC]
-
-# JSON Pointer {#JsonPointer}
-
-A JSON Pointer is a list of zero-to-many tokens, each prefixed by `/`. Each token can be a string or a number. For example, given a JSON:
-~~~javascript
-{
-    "foo" : ["bar", "baz"],
-    "pi" : 3.1416
-}
-~~~
-
-The following JSON Pointers resolve this JSON as:
-
-1. `"/foo"` → `[ "bar", "baz" ]`
-2. `"/foo/0"` → `"bar"`
-3. `"/foo/1"` → `"baz"`
-4. `"/pi"` → `3.1416`
-
-Note that, an empty JSON Pointer `""` (zero token) resolves to the whole JSON.
-
-# Basic Usage {#BasicUsage}
-
-The following example code is self-explanatory.
-
-~~~cpp
-#include "rapidjson/pointer.h"
-
-// ...
-Document d;
-
-// Create DOM by Set()
-Pointer("/project").Set(d, "RapidJSON");
-Pointer("/stars").Set(d, 10);
-
-// { "project" : "RapidJSON", "stars" : 10 }
-
-// Access DOM by Get(). It return nullptr if the value does not exist.
-if (Value* stars = Pointer("/stars").Get(d))
-    stars->SetInt(stars->GetInt() + 1);
-
-// { "project" : "RapidJSON", "stars" : 11 }
-
-// Set() and Create() automatically generate parents if not exist.
-Pointer("/a/b/0").Create(d);
-
-// { "project" : "RapidJSON", "stars" : 11, "a" : { "b" : [ null ] } }
-
-// GetWithDefault() returns reference. And it deep clones the default value.
-Value& hello = Pointer("/hello").GetWithDefault(d, "world");
-
-// { "project" : "RapidJSON", "stars" : 11, "a" : { "b" : [ null ] }, "hello" : "world" }
-
-// Swap() is similar to Set()
-Value x("C++");
-Pointer("/hello").Swap(d, x);
-
-// { "project" : "RapidJSON", "stars" : 11, "a" : { "b" : [ null ] }, "hello" : "C++" }
-// x becomes "world"
-
-// Erase a member or element, return true if the value exists
-bool success = Pointer("/a").Erase(d);
-assert(success);
-
-// { "project" : "RapidJSON", "stars" : 10 }
-~~~
-
-# Helper Functions {#HelperFunctions}
-
-Since object-oriented calling convention may be non-intuitive, RapidJSON also provides helper functions, which just wrap the member functions with free-functions.
-
-The following example does exactly the same as the above one.
-
-~~~cpp
-Document d;
-
-SetValueByPointer(d, "/project", "RapidJSON");
-SetValueByPointer(d, "/stars", 10);
-
-if (Value* stars = GetValueByPointer(d, "/stars"))
-    stars->SetInt(stars->GetInt() + 1);
-
-CreateValueByPointer(d, "/a/b/0");
-
-Value& hello = GetValueByPointerWithDefault(d, "/hello", "world");
-
-Value x("C++");
-SwapValueByPointer(d, "/hello", x);
-
-bool success = EraseValueByPointer(d, "/a");
-assert(success);
-~~~
-
-The conventions are shown here for comparison:
-
-1. `Pointer(source).<Method>(root, ...)`
-2. `<Method>ValueByPointer(root, Pointer(source), ...)`
-3. `<Method>ValueByPointer(root, source, ...)`
-
-# Resolving Pointer {#ResolvingPointer}
-
-`Pointer::Get()` or `GetValueByPointer()` function does not modify the DOM. If the tokens cannot match a value in the DOM, it returns `nullptr`. User can use this to check whether a value exists.
-
-Note that, numerical tokens can represent an array index or member name. The resolving process will match the values according to the types of value.
-
-~~~javascript
-{
-    "0" : 123,
-    "1" : [456]
-}
-~~~
-
-1. `"/0"` → `123`
-2. `"/1/0"` → `456`
-
-The token `"0"` is treated as member name in the first pointer. It is treated as an array index in the second pointer.
-
-The other functions, including `Create()`, `GetWithDefault()`, `Set()` and `Swap()`, will change the DOM. These functions will always succeed. They will create the parent values if they do not exist. If the parent values do not match the tokens, they will also be forced to change their type. Changing the type also mean fully removal of that DOM subtree.
-
-Parsing the above JSON into `d`, 
-
-~~~cpp
-SetValueByPointer(d, "1/a", 789); // { "0" : 123, "1" : { "a" : 789 } }
-~~~
-
-## Resolving Minus Sign Token
-
-Besides, [RFC6901] defines a special token `-` (single minus sign), which represents the pass-the-end element of an array. `Get()` only treats this token as a member name '"-"'. Yet the other functions can resolve this for array, equivalent to calling `Value::PushBack()` to the array.
-
-~~~cpp
-Document d;
-d.Parse("{\"foo\":[123]}");
-SetValueByPointer(d, "/foo/-", 456); // { "foo" : [123, 456] }
-SetValueByPointer(d, "/-", 789);    // { "foo" : [123, 456], "-" : 789 }
-~~~
-
-## Resolving Document and Value
-
-When using `p.Get(root)` or `GetValueByPointer(root, p)`, `root` is a (const) `Value&`. That means, it can be a subtree of the DOM.
-
-The other functions have two groups of signature. One group uses `Document& document` as parameter, another one uses `Value& root`. The first group uses `document.GetAllocator()` for creating values. And the second group needs user to supply an allocator, like the functions in DOM.
-
-All examples above do not require an allocator parameter, because the first parameter is a `Document&`. But if you want to resolve a pointer to a subtree, you need to supply the allocator as in the following example:
-
-~~~cpp
-class Person {
-public:
-    Person() {
-        document_ = new Document();
-        // CreateValueByPointer() here no need allocator
-        SetLocation(CreateValueByPointer(*document_, "/residence"), ...);
-        SetLocation(CreateValueByPointer(*document_, "/office"), ...);
-    };
-
-private:
-    void SetLocation(Value& location, const char* country, const char* addresses[2]) {
-        Value::Allocator& a = document_->GetAllocator();
-        // SetValueByPointer() here need allocator
-        SetValueByPointer(location, "/country", country, a);
-        SetValueByPointer(location, "/address/0", address[0], a);
-        SetValueByPointer(location, "/address/1", address[1], a);
-    }
-
-    // ...
-
-    Document* document_;
-};
-~~~
-
-`Erase()` or `EraseValueByPointer()` does not need allocator. And they return `true` if the value is erased successfully.
-
-# Error Handling {#ErrorHandling}
-
-A `Pointer` parses a source string in its constructor. If there is parsing error, `Pointer::IsValid()` returns `false`. And you can use `Pointer::GetParseErrorCode()` and `GetParseErrorOffset()` to retrieve the error information.
-
-Note that, all resolving functions assumes valid pointer. Resolving with an invalid pointer causes assertion failure.
-
-# URI Fragment Representation {#URIFragment}
-
-In addition to the string representation of JSON pointer that we are using till now, [RFC6901] also defines the URI fragment representation of JSON pointer. URI fragment is specified in [RFC3986] "Uniform Resource Identifier (URI): Generic Syntax".
-
-The main differences are that a the URI fragment always has a `#` (pound sign) in the beginning, and some characters are encoded by percent-encoding in UTF-8 sequence. For example, the following table shows different C/C++ string literals of different representations.
-
-String Representation | URI Fragment Representation | Pointer Tokens (UTF-8)
-----------------------|-----------------------------|------------------------
-`"/foo/0"`            | `"#/foo/0"`                 | `{"foo", 0}`
-`"/a~1b"`             | `"#/a~1b"`                  | `{"a/b"}`
-`"/m~0n"`             | `"#/m~0n"`                  | `{"m~n"}`
-`"/ "`                | `"#/%20"`                   | `{" "}`
-`"/\0"`               | `"#/%00"`                   | `{"\0"}`
-`"/€"`                | `"#/%E2%82%AC"`             | `{"€"}`
-
-RapidJSON fully support URI fragment representation. It automatically detects the pound sign during parsing.
-
-# Stringify
-
-You may also stringify a `Pointer` to a string or other output streams. This can be done by:
-
-~~~
-Pointer p(...);
-StringBuffer sb;
-p.Stringify(sb);
-std::cout << sb.GetString() << std::endl;
-~~~
-
-It can also stringify to URI fragment representation by `StringifyUriFragment()`.
-
-# User-Supplied Tokens {#UserSuppliedTokens}
-
-If a pointer will be resolved multiple times, it should be constructed once, and then apply it to different DOMs or in different times. This reduce time and memory allocation for constructing `Pointer` multiple times.
-
-We can go one step further, to completely eliminate the parsing process and dynamic memory allocation, we can establish the token array directly:
-
-~~~cpp
-#define NAME(s) { s, sizeof(s) / sizeof(s[0]) - 1, kPointerInvalidIndex }
-#define INDEX(i) { #i, sizeof(#i) - 1, i }
-
-static const Pointer::Token kTokens[] = { NAME("foo"), INDEX(123) };
-static const Pointer p(kTokens, sizeof(kTokens) / sizeof(kTokens[0]));
-// Equivalent to static const Pointer p("/foo/123");
-~~~
-
-This may be useful for memory constrained systems.
-
-[RFC3986]: https://tools.ietf.org/html/rfc3986
-[RFC6901]: https://tools.ietf.org/html/rfc6901

package/external/rapidjson/doc/pointer.zh-cn.md

@@ -1,234 +0,0 @@
-# Pointer
-
-（本功能于 v1.1.0 发布）
-
-JSON Pointer 是一个标准化（[RFC6901]）的方式去选取一个 JSON Document（DOM）中的值。这类似于 XML 的 XPath。然而，JSON Pointer 简单得多，而且每个 JSON Pointer 仅指向单个值。
-
-使用 RapidJSON 的 JSON Pointer 实现能简化一些 DOM 的操作。
-
-[TOC]
-
-# JSON Pointer {#JsonPointer}
-
-一个 JSON Pointer 由一串（零至多个）token 所组成，每个 token 都有 `/` 前缀。每个 token 可以是一个字符串或数字。例如，给定一个 JSON：
-~~~javascript
-{
-    "foo" : ["bar", "baz"],
-    "pi" : 3.1416
-}
-~~~
-
-以下的 JSON Pointer 解析为：
-
-1. `"/foo"` → `[ "bar", "baz" ]`
-2. `"/foo/0"` → `"bar"`
-3. `"/foo/1"` → `"baz"`
-4. `"/pi"` → `3.1416`
-
-要注意，一个空 JSON Pointer `""` （零个 token）解析为整个 JSON。
-
-# 基本使用方法 {#BasicUsage}
-
-以下的代码范例不解自明。
-
-~~~cpp
-#include "rapidjson/pointer.h"
-
-// ...
-Document d;
-
-// 使用 Set() 创建 DOM
-Pointer("/project").Set(d, "RapidJSON");
-Pointer("/stars").Set(d, 10);
-
-// { "project" : "RapidJSON", "stars" : 10 }
-
-// 使用 Get() 访问 DOM。若该值不存在则返回 nullptr。
-if (Value* stars = Pointer("/stars").Get(d))
-    stars->SetInt(stars->GetInt() + 1);
-
-// { "project" : "RapidJSON", "stars" : 11 }
-
-// Set() 和 Create() 自动生成父值（如果它们不存在）。
-Pointer("/a/b/0").Create(d);
-
-// { "project" : "RapidJSON", "stars" : 11, "a" : { "b" : [ null ] } }
-
-// GetWithDefault() 返回引用。若该值不存在则会深拷贝缺省值。
-Value& hello = Pointer("/hello").GetWithDefault(d, "world");
-
-// { "project" : "RapidJSON", "stars" : 11, "a" : { "b" : [ null ] }, "hello" : "world" }
-
-// Swap() 和 Set() 相似
-Value x("C++");
-Pointer("/hello").Swap(d, x);
-
-// { "project" : "RapidJSON", "stars" : 11, "a" : { "b" : [ null ] }, "hello" : "C++" }
-// x 变成 "world"
-
-// 删去一个成员或元素，若值存在返回 true
-bool success = Pointer("/a").Erase(d);
-assert(success);
-
-// { "project" : "RapidJSON", "stars" : 10 }
-~~~
-
-# 辅助函数 {#HelperFunctions}
-
-由于面向对象的调用习惯可能不符直觉，RapidJSON 也提供了一些辅助函数，它们把成员函数包装成自由函数。
-
-以下的例子与上面例子所做的事情完全相同。
-
-~~~cpp
-Document d;
-
-SetValueByPointer(d, "/project", "RapidJSON");
-SetValueByPointer(d, "/stars", 10);
-
-if (Value* stars = GetValueByPointer(d, "/stars"))
-    stars->SetInt(stars->GetInt() + 1);
-
-CreateValueByPointer(d, "/a/b/0");
-
-Value& hello = GetValueByPointerWithDefault(d, "/hello", "world");
-
-Value x("C++");
-SwapValueByPointer(d, "/hello", x);
-
-bool success = EraseValueByPointer(d, "/a");
-assert(success);
-~~~
-
-以下对比 3 种调用方式：
-
-1. `Pointer(source).<Method>(root, ...)`
-2. `<Method>ValueByPointer(root, Pointer(source), ...)`
-3. `<Method>ValueByPointer(root, source, ...)`
-
-# 解析 Pointer {#ResolvingPointer}
-
-`Pointer::Get()` 或 `GetValueByPointer()` 函数并不修改 DOM。若那些 token 不能匹配 DOM 里的值，这些函数便返回 `nullptr`。使用者可利用这个方法来检查一个值是否存在。
-
-注意，数值 token 可表示数组索引或成员名字。解析过程中会按值的类型来匹配。
-
-~~~javascript
-{
-    "0" : 123,
-    "1" : [456]
-}
-~~~
-
-1. `"/0"` → `123`
-2. `"/1/0"` → `456`
-
-Token `"0"` 在第一个 pointer 中被当作成员名字。它在第二个 pointer 中被当作成数组索引。
-
-其他函数会改变 DOM，包括 `Create()`、`GetWithDefault()`、`Set()`、`Swap()`。这些函数总是成功的。若一些父值不存在，就会创建它们。若父值类型不匹配 token，也会强行改变其类型。改变类型也意味着完全移除其 DOM 子树的内容。
-
-例如，把上面的 JSON 解译至 `d` 之后，
-
-~~~cpp
-SetValueByPointer(d, "1/a", 789); // { "0" : 123, "1" : { "a" : 789 } }
-~~~
-
-## 解析负号 token
-
-另外，[RFC6901] 定义了一个特殊 token `-` （单个负号），用于表示数组最后元素的下一个元素。 `Get()` 只会把此 token 当作成员名字 '"-"'。而其他函数则会以此解析数组，等同于对数组调用 `Value::PushBack()` 。
-
-~~~cpp
-Document d;
-d.Parse("{\"foo\":[123]}");
-SetValueByPointer(d, "/foo/-", 456); // { "foo" : [123, 456] }
-SetValueByPointer(d, "/-", 789);    // { "foo" : [123, 456], "-" : 789 }
-~~~
-
-## 解析 Document 及 Value
-
-当使用 `p.Get(root)` 或 `GetValueByPointer(root, p)`，`root` 是一个（常数） `Value&`。这意味着，它也可以是 DOM 里的一个子树。
-
-其他函数有两组签名。一组使用 `Document& document` 作为参数，另一组使用 `Value& root`。第一组使用 `document.GetAllocator()` 去创建值，而第二组则需要使用者提供一个 allocator，如同 DOM 里的函数。
-
-以上例子都不需要 allocator 参数，因为它的第一个参数是 `Document&`。但如果你需要对一个子树进行解析，就需要如下面的例子般提供 allocator：
-
-~~~cpp
-class Person {
-public:
-    Person() {
-        document_ = new Document();
-        // CreateValueByPointer() here no need allocator
-        SetLocation(CreateValueByPointer(*document_, "/residence"), ...);
-        SetLocation(CreateValueByPointer(*document_, "/office"), ...);
-    };
-
-private:
-    void SetLocation(Value& location, const char* country, const char* addresses[2]) {
-        Value::Allocator& a = document_->GetAllocator();
-        // SetValueByPointer() here need allocator
-        SetValueByPointer(location, "/country", country, a);
-        SetValueByPointer(location, "/address/0", address[0], a);
-        SetValueByPointer(location, "/address/1", address[1], a);
-    }
-
-    // ...
-
-    Document* document_;
-};
-~~~
-
-`Erase()` 或 `EraseValueByPointer()` 不需要 allocator。而且它们成功删除值之后会返回 `true`。
-
-# 错误处理 {#ErrorHandling}
-
-`Pointer` 在其建构函数里会解译源字符串。若有解析错误，`Pointer::IsValid()` 返回 `false`。你可使用 `Pointer::GetParseErrorCode()` 和 `GetParseErrorOffset()` 去获取错信息。
-
-要注意的是，所有解析函数都假设 pointer 是合法的。对一个非法 pointer 解析会做成断言失败。
-
-# URI 片段表示方式 {#URIFragment}
-
-除了我们一直在使用的字符串方式表示 JSON pointer，[RFC6901] 也定义了一个 JSON Pointer 的 URI 片段（fragment）表示方式。URI 片段是定义于 [RFC3986] "Uniform Resource Identifier (URI): Generic Syntax"。
-
-URI 片段的主要分别是必然以 `#` （pound sign）开头，而一些字符也会以百分比编码成 UTF-8 序列。例如，以下的表展示了不同表示法下的 C/C++ 字符串常数。
-
-字符串表示方式 | URI 片段表示方式 | Pointer Tokens （UTF-8）
-----------------------|-----------------------------|------------------------
-`"/foo/0"`            | `"#/foo/0"`                 | `{"foo", 0}`
-`"/a~1b"`             | `"#/a~1b"`                  | `{"a/b"}`
-`"/m~0n"`             | `"#/m~0n"`                  | `{"m~n"}`
-`"/ "`                | `"#/%20"`                   | `{" "}`
-`"/\0"`               | `"#/%00"`                   | `{"\0"}`
-`"/€"`                | `"#/%E2%82%AC"`             | `{"€"}`
-
-RapidJSON 完全支持 URI 片段表示方式。它在解译时会自动检测 `#` 号。
-
-# 字符串化
-
-你也可以把一个 `Pointer` 字符串化，储存于字符串或其他输出流。例如：
-
-~~~
-Pointer p(...);
-StringBuffer sb;
-p.Stringify(sb);
-std::cout << sb.GetString() << std::endl;
-~~~
-
-使用 `StringifyUriFragment()` 可以把 pointer 字符串化为 URI 片段表示法。
-
-# 使用者提供的 tokens {#UserSuppliedTokens}
-
-若一个 pointer 会用于多次解析，它应该只被创建一次，然后再施于不同的 DOM ，或在不同时间做解析。这样可以避免多次创键 `Pointer`，节省时间和内存分配。
-
-我们甚至可以再更进一步，完全消去解析过程及动态内存分配。我们可以直接生成 token 数组：
-
-~~~cpp
-#define NAME(s) { s, sizeof(s) / sizeof(s[0]) - 1, kPointerInvalidIndex }
-#define INDEX(i) { #i, sizeof(#i) - 1, i }
-
-static const Pointer::Token kTokens[] = { NAME("foo"), INDEX(123) };
-static const Pointer p(kTokens, sizeof(kTokens) / sizeof(kTokens[0]));
-// Equivalent to static const Pointer p("/foo/123");
-~~~
-
-这种做法可能适合内存受限的系统。
-
-[RFC3986]: https://tools.ietf.org/html/rfc3986
-[RFC6901]: https://tools.ietf.org/html/rfc6901