diff options
author | Milo Yip <miloyip@gmail.com> | 2014-07-06 18:43:52 +0400 |
---|---|---|
committer | Milo Yip <miloyip@gmail.com> | 2014-07-06 18:43:52 +0400 |
commit | 698496e3f37d785352d971faa3c9c46704cf12fc (patch) | |
tree | df78f1573d45994c474959f4fea6f2d78ba90432 /doc | |
parent | 4cadecd32d6159aae434a64b35aa8a59ea9dca58 (diff) |
Minor document adjustments
Diffstat (limited to 'doc')
-rw-r--r-- | doc/stream.md | 60 | ||||
-rw-r--r-- | doc/tutorial.md | 140 |
2 files changed, 100 insertions, 100 deletions
diff --git a/doc/stream.md b/doc/stream.md index ebc34d51..441dbaa1 100644 --- a/doc/stream.md +++ b/doc/stream.md @@ -10,7 +10,7 @@ Memory streams store JSON in memory. `StringStream` is the most basic input stream. It represents a complete, read-only JSON stored in memory. It is defined in `rapidjson/rapidjson.h`. -```cpp +~~~~~~~~~~cpp #include "rapidjson/document.h" // will include "rapidjson/rapidjson.h" using namespace rapidjson; @@ -21,16 +21,16 @@ StringStream s(json); Document d; d.ParseStream(s); -``` +~~~~~~~~~~ Since this is very common usage, `Document::Parse(const char*)` is provided to do exactly the same as above: -```cpp +~~~~~~~~~~cpp // ... const char json[] = "[1, 2, 3, 4]"; Document d; d.Parse(json); -``` +~~~~~~~~~~ Note that, `StringStream` is a typedef of `GenericStringStream<UTF8<> >`, user may use another encodings to represent the character set of the stream. @@ -38,7 +38,7 @@ Note that, `StringStream` is a typedef of `GenericStringStream<UTF8<> >`, user m `StringBuffer` is a simple output stream. It allocates a memory buffer for writing the whole JSON. Use `GetString()` to obtain the buffer. -```cpp +~~~~~~~~~~cpp #include "rapidjson/stringbuffer.h" StringBuffer buffer; @@ -46,14 +46,14 @@ Writer<StringBuffer> writer(buffer); d.Accept(writer); const char* output = buffer.GetString(); -``` +~~~~~~~~~~ When the buffer is full, it will increases the capacity automatically. The default capacity is 256 characters (256 bytes for UTF8, 512 bytes for UTF16, etc.). User can provide an allocator and a initial capacity. -```cpp +~~~~~~~~~~cpp StringBuffer buffer1(0, 1024); // Use its allocator, initial size = 1024 StringBuffer buffer2(allocator, 1024); -``` +~~~~~~~~~~ By default, `StringBuffer` will instantiate an internal allocator. @@ -69,7 +69,7 @@ However, if the JSON is big, or memory is limited, you can use `FileReadStream`. `FileReadStream` reads the file via a `FILE` pointer. And user need to provide a buffer. -```cpp +~~~~~~~~~~cpp #include "rapidjson/filereadstream.h" #include <cstdio> @@ -82,7 +82,7 @@ Document d; d.ParseStream(is); fclose(fp); -``` +~~~~~~~~~~ Different from string streams, `FileReadStream` is byte stream. It does not handle encodings. If the file is not UTF-8, the byte stream can be wrapped in a `EncodedInputStream`. It will be discussed very soon. @@ -92,7 +92,7 @@ Apart from reading file, user can also use `FileReadStream` to read `stdin`. `FileWriteStream` is buffered output stream. Its usage is very similar to `FileReadStream`. -```cpp +~~~~~~~~~~cpp #include "rapidjson/filewritestream.h" #include <cstdio> @@ -109,7 +109,7 @@ Writer<FileWriteStream> writer(os); d.Accept(writer); fclose(fp); -``` +~~~~~~~~~~ It can also directs the output to `stdout`. @@ -129,7 +129,7 @@ Note that, these encoded streams can be applied to streams other than file. For `EncodedInputStream` has two template parameters. The first one is a `Encoding` class, such as `UTF8`, `UTF16LE`, defined in `rapidjson/encodings.h`. The second one is the class of stream to be wrapped. -```cpp +~~~~~~~~~~cpp #include "rapidjson/document.h" #include "rapidjson/filereadstream.h" // FileReadStream #include "rapidjson/encodedstream.h" // EncodedInputStream @@ -148,13 +148,13 @@ Document d; // Document is GenericDocument<UTF8<> > d.ParseStream<0, UTF16LE<> >(eis); // Parses UTF-16LE file into UTF-8 in memory fclose(fp); -``` +~~~~~~~~~~ ### EncodedOutputStream `EncodedOutputStream` is similar but it has a `bool putBOM` parameter in the constructor, controlling whether to write BOM into output byte stream. -```cpp +~~~~~~~~~~cpp #include "rapidjson/filewritestream.h" // FileWriteStream #include "rapidjson/encodedstream.h" // EncodedOutputStream #include <cstdio> @@ -174,7 +174,7 @@ Writer<OutputStream, UTF32LE<>, UTF8<>> writer(eos); d.Accept(writer); // This generates UTF32-LE file from UTF-8 in memory fclose(fp); -``` +~~~~~~~~~~ ### AutoUTFInputStream @@ -182,7 +182,7 @@ Sometimes an application may want to handle all supported JSON encoding. `AutoUT Since the characters (code units) may be 8-bit, 16-bit or 32-bit. `AutoUTFInputStream` requires a character type which can hold at least 32-bit. We may use `unsigned`, as in the template parameter: -```cpp +~~~~~~~~~~cpp #include "rapidjson/document.h" #include "rapidjson/filereadstream.h" // FileReadStream #include "rapidjson/encodedstream.h" // AutoUTFInputStream @@ -201,7 +201,7 @@ Document d; // Document is GenericDocument<UTF8<> > d.ParseStream<0, AutoUTF<unsigned> >(eis); // This parses any UTF file into UTF-8 in memory fclose(fp); -``` +~~~~~~~~~~ When specifying the encoding of stream, uses `AutoUTF<CharType>` as in `ParseStream()` above. @@ -211,7 +211,7 @@ You can obtain the type of UTF via `UTFType GetType()`. And check whether a BOM Similarly, to choose encoding for output during runtime, we can use `AutoUTFOutputStream`. This class is not automatic *per se*. You need to specify the UTF type and whether to write BOM in runtime. -```cpp +~~~~~~~~~~cpp void WriteJSONFile(FILE* fp, UTFType type, bool putBOM, const Document& d) { char writeBuffer[256]; FileWriteStream bos(fp, writeBuffer, sizeof(writeBuffer)); @@ -222,7 +222,7 @@ void WriteJSONFile(FILE* fp, UTFType type, bool putBOM, const Document& d) { Writer<OutputStream, UTF8<>, AutoUTF<> > writer; d.Accept(writer); } -``` +~~~~~~~~~~ `AutoUTFInputStream` and `AutoUTFOutputStream` is more convenient than `EncodedInputStream` and `EncodedOutputStream`. They just incur a little bit runtime overheads. @@ -232,7 +232,7 @@ In addition to memory/file streams, user can create their own stream classes whi RapidJSON combines different types using templates. A class containing all required interface can be a stream. The Stream interface is defined in comments of `rapidjson/rapidjson.h`: -```cpp +~~~~~~~~~~cpp concept Stream { typename Ch; //!< Character type of the stream. @@ -261,7 +261,7 @@ concept Stream { //! \return Number of characters written. size_t PutEnd(Ch* begin); } -``` +~~~~~~~~~~ For input stream, they must implement `Peek()`, `Take()` and `Tell()`. For output stream, they must implement `Put()` and `Flush()`. @@ -271,7 +271,7 @@ There are two special interface, `PutBegin()` and `PutEnd()`, which are only for The following example is a wrapper of `std::istream`, which only implements 3 functions. -```cpp +~~~~~~~~~~cpp class IStreamWrapper { public: typedef char Ch; @@ -302,18 +302,18 @@ private: std::istream& is_; }; -``` +~~~~~~~~~~ User can use it to wrap instances of `std::stringstream`, `std::ifstream`. -```cpp +~~~~~~~~~~cpp const char* json = "[1,2,3,4]"; std::stringstream ss(json); IStreamWrapper is(ss); Document d; d.Parse(is); -``` +~~~~~~~~~~ Note that, this implementation may not be as efficient as RapidJSON's memory or file streams, due to internal overheads of the standard library. @@ -321,7 +321,7 @@ Note that, this implementation may not be as efficient as RapidJSON's memory or The following example is a wrapper of `std::istream`, which only implements 2 functions. -```cpp +~~~~~~~~~~cpp class OStreamWrapper { public: typedef char Ch; @@ -344,11 +344,11 @@ private: std::ostream& os_; }; -``` +~~~~~~~~~~ User can use it to wrap instances of `std::stringstream`, `std::ofstream`. -```cpp +~~~~~~~~~~cpp Document d; // ... @@ -357,7 +357,7 @@ OSStreamWrapper os(ss); Writer<OStreamWrapper> writer(os); d.Accept(writer); -``` +~~~~~~~~~~ Note that, this implementation may not be as efficient as RapidJSON's memory or file streams, due to internal overheads of the standard library. diff --git a/doc/tutorial.md b/doc/tutorial.md index eb6a1504..0b3da16d 100644 --- a/doc/tutorial.md +++ b/doc/tutorial.md @@ -2,18 +2,18 @@ This tutorial introduces the basics of the Document Object Model(DOM) API. -As shown in [Usage at a glance](../readme.md#usage-at-a-glance), a JSON text can be parsed into DOM, and then the DOM can be queried and modified easily, and finally be converted back to JSON text. +As shown in [Usage at a glance](../readme.md#usage-at-a-glance), a JSON can be parsed into DOM, and then the DOM can be queried and modified easily, and finally be converted back to JSON. ## Value & Document -Each JSON value is stored in a type called `Value`. A `Document`, representing the DOM, contains the root of `Value`. +Each JSON value is stored in a type called `Value`. A `Document`, representing the DOM, contains the root of `Value`. All public types and functions of RapidJSON are defined in the `rapidjson` namespace. ### Query Value In this section, we will use excerpt of [`example/tutorial/tutorial.cpp`](../example/tutorial/tutorial.cpp). -Assumes we have a JSON text stored in a C string (`const char* json`): -```js +Assumes we have a JSON stored in a C string (`const char* json`): +~~~~~~~~~~js { "hello": "world", "t": true , @@ -23,10 +23,10 @@ Assumes we have a JSON text stored in a C string (`const char* json`): "pi": 3.1416, "a": [1, 2, 3, 4] } -``` +~~~~~~~~~~ Parse it into a `Document` -```cpp +~~~~~~~~~~cpp #include "rapidjson/document.h" using namespace rapidjson; @@ -34,50 +34,50 @@ using namespace rapidjson; // ... Document document; document.Parse(json); -``` +~~~~~~~~~~ -The JSON text is now parsed into `document` as a *DOM tree*: +The JSON is now parsed into `document` as a *DOM tree*: -![tutorial](diagram/tutorial.png?raw=true) +![tutorial](diagram/tutorial.png) The root of a conforming JSON should be either an object or an array. In this case, the root is an object. -```cpp +~~~~~~~~~~cpp assert(document.IsObject()); -``` +~~~~~~~~~~ Query whether a `"hello"` member exists in the root object. Since a `Value` can contain different types of value, we may need to verify its type and use suitable API to obtain the value. In this example, `"hello"` member associates with a JSON string. -```cpp +~~~~~~~~~~cpp assert(document.HasMember("hello")); assert(document["hello"].IsString()); printf("hello = %s\n", document["hello"].GetString()); -``` +~~~~~~~~~~ -``` +~~~~~~~~~~ world -``` +~~~~~~~~~~ JSON true/false values are represented as `bool`. -```cpp +~~~~~~~~~~cpp assert(document["t"].IsBool()); printf("t = %s\n", document["t"].GetBool() ? "true" : "false"); -``` +~~~~~~~~~~ -``` +~~~~~~~~~~ true -``` +~~~~~~~~~~ JSON null can be queryed by `IsNull()`. -```cpp +~~~~~~~~~~cpp printf("n = %s\n", document["n"].IsNull() ? "null" : "?"); -``` +~~~~~~~~~~ -``` +~~~~~~~~~~ null -``` +~~~~~~~~~~ JSON number type represents all numeric values. However, C++ needs more specific type for manipulation. -```cpp +~~~~~~~~~~cpp assert(document["i"].IsNumber()); // In this case, IsUint()/IsInt64()/IsUInt64() also return true. @@ -88,28 +88,28 @@ printf("i = %d\n", document["i"].GetInt()); assert(document["pi"].IsNumber()); assert(document["pi"].IsDouble()); printf("pi = %g\n", document["pi"].GetDouble()); -``` +~~~~~~~~~~ -``` +~~~~~~~~~~ i = 123 pi = 3.1416 -``` +~~~~~~~~~~ JSON array contains a number of elements. -```cpp +~~~~~~~~~~cpp // Using a reference for consecutive access is handy and faster. const Value& a = document["a"]; assert(a.IsArray()); for (SizeType i = 0; i < a.Size(); i++) // Uses SizeType instead of size_t printf("a[%d] = %d\n", i, a[i].GetInt()); -``` +~~~~~~~~~~ -``` +~~~~~~~~~~ a[0] = 1 a[1] = 2 a[2] = 3 a[3] = 4 -``` +~~~~~~~~~~ Note that, RapidJSON does not automatically convert values between JSON types. If a value is a string, it is invalid to call `GetInt()`, for example. In debug mode it will fail an assertion. In release mode, the behavior is undefined. @@ -124,10 +124,10 @@ You may access the elements in array by integer literal, for example, `a[1]`, `a * `a[0u]` Array is similar to `std::vector`, instead of using indices, you may also use iterator to access all the elements. -```cpp +~~~~~~~~~~cpp for (Value::ConstValueIterator itr = a.Begin(); itr != a.End(); ++itr) printf("%d ", itr->GetInt()); -``` +~~~~~~~~~~ And other familiar query functions: * `SizeType Capacity() const` @@ -137,7 +137,7 @@ And other familiar query functions: Similar to array, we can iterate object members by iterator: -```cpp +~~~~~~~~~~cpp static const char* kTypeNames[] = { "Null", "False", "True", "Object", "Array", "String", "Number" }; @@ -147,9 +147,9 @@ for (Value::ConstMemberIterator itr = document.MemberBegin(); printf("Type of member %s is %s\n", itr->name.GetString(), kTypeNames[itr->value.GetType()]); } -``` +~~~~~~~~~~ -``` +~~~~~~~~~~ Type of member hello is String Type of member t is True Type of member f is False @@ -157,17 +157,17 @@ Type of member n is Null Type of member i is Number Type of member pi is Number Type of member a is Array -``` +~~~~~~~~~~ Note that, when `operator[](const char*)` cannot find the member, it will fail an assertion. If we are unsure whether a member exists, we need to call `HasMember()` before calling `operator[](const char*)`. However, this incurs two lookup. A better way is to call `FindMember()`, which can check the existence of member and obtain its value at once: -```cpp +~~~~~~~~~~cpp Value::ConstMemberIterator itr = document.FindMember("hello"); if (itr != document.MemberEnd()) printf("%s %s\n", itr->value.GetString()); -``` +~~~~~~~~~~ ### Querying Number @@ -210,18 +210,18 @@ To conform RFC 4627, RapidJSON supports string containing `U+0000`. If you need For example, after parsing a the following JSON string to `Document d`. -```js +~~~~~~~~~~js { "s" : "a\u0000b" } -``` +~~~~~~~~~~ The correct length of the value `"a\u0000b"` is 3. But `strlen()` returns 1. `GetStringLength()` can also improve performance, as user may often need to call `strlen()` for allocating buffer. Besides, `std::string` also support a constructor: -```cpp +~~~~~~~~~~cpp string( const char* s, size_type count); -``` +~~~~~~~~~~ which accepts the length of string as parameter. This constructor supports storing null character within the string, and should also provide better performance. @@ -232,43 +232,43 @@ There are several ways to create values. After a DOM tree is created and/or modi ### Changing Value Type When creating a Value or Document by default constructor, its type is Null. To change its type, call `SetXXX()` or assignment operator, for example: -```cpp +~~~~~~~~~~cpp Document d; // Null d.SetObject(); Value v; // Null v.SetInt(10); v = 10; // Shortcut, same as above -``` +~~~~~~~~~~ ### Overloaded Constructors There are also overloaded constructors for several types: -```cpp +~~~~~~~~~~cpp Value b(true); // calls Value(bool) Value i(-123); // calls Value(int) Value u(123u); // calls Value(unsigned) Value d(1.5); // calls Value(double) -``` +~~~~~~~~~~ To create empty object or array, you may use `SetObject()`/`SetArray()` after default constructor, or using the `Value(Type)` in one shot: -```cpp +~~~~~~~~~~cpp Value o(kObjectType); Value a(kArrayType); -``` +~~~~~~~~~~ ### Move Semantics A very special decision during design of RapidJSON is that, assignment of value does not copy the source value to destination value. Instead, the value from source is moved to the destination. For example, -```cpp +~~~~~~~~~~cpp Value a(123); Value b(456); b = a; // a becomes a Null value, b becomes number 123. -``` +~~~~~~~~~~ -![move1](diagram/move1.png?raw=true) +![move1](diagram/move1.png) Why? What is the advantage of this semantics? @@ -276,7 +276,7 @@ The simple answer is performance. For fixed size JSON types (Number, True, False For example, if normal *copy* semantics was used: -```cpp +~~~~~~~~~~cpp Value o(kObjectType); { Value contacts(kArrayType); @@ -285,9 +285,9 @@ Value o(kObjectType); o.AddMember("contacts", contacts); // deep clone contacts (may be with lots of allocations) // destruct contacts. } -``` +~~~~~~~~~~ -![move2](diagram/move2.png?raw=true) +![move2](diagram/move2.png) The object `o` needs to allocate a buffer of same size as contacts, makes a deep clone of it, and then finally contacts is destructed. This will incur a lot of unnecessary allocations/deallocations and memory copying. @@ -297,7 +297,7 @@ To make RapidJSON simple and fast, we chose to use *move* semantics for assignme So, with move semantics, the above example becomes: -```cpp +~~~~~~~~~~cpp Value o(kObjectType); { Value contacts(kArrayType); @@ -305,9 +305,9 @@ Value o(kObjectType); o.AddMember("contacts", contacts); // just memcpy() of contacts itself to the value of new member (16 bytes) // contacts became Null here. Its destruction is trivial. } -``` +~~~~~~~~~~ -![move3](diagram/move3.png?raw=true) +![move3](diagram/move3.png) This is called move assignment operator in C++11. As RapidJSON supports C++03, it adopts move semantics using assignment operator, and all other modifying function like `AddMember()`, `PushBack()`. @@ -323,7 +323,7 @@ To make memory allocation customizable, RapidJSON requires user to pass an insta Therefore, when we assign a copy-string, we call this overloaded `SetString()` with allocator: -```cpp +~~~~~~~~~~cpp Document document; Value author; char buffer[10]; @@ -331,7 +331,7 @@ int len = sprintf(buffer, "%s %s", "Milo", "Yip"); // dynamically created string author.SetString(buffer, len, document.GetAllocator()); memset(buffer, 0, sizeof(buffer)); // author.GetString() still contains "Milo Yip" after buffer is destroyed -``` +~~~~~~~~~~ In this example, we get the allocator from a `Document` instance. This is a common idiom when using RapidJSON. But you may use other instances of allocator. @@ -339,12 +339,12 @@ Besides, the above `SetString()` requires length. This can handle null character Finally, for literal string or string with safe life-cycle can use const-string version of `SetString()`, which lacks allocator parameter: -```cpp +~~~~~~~~~~cpp Value s; s.SetString("rapidjson", 9); // faster, can contain null character s.SetString("rapidjson"); // slower, assumes null-terminated s = "rapidjson"; // shortcut, same as above -``` +~~~~~~~~~~ ### Modify Array Value with array type provides similar APIs as `std::vector`. @@ -359,7 +359,7 @@ Note that, `Reserve(...)` and `PushBack(...)` may allocate memory, therefore req Here is an example of `PushBack()`: -```cpp +~~~~~~~~~~cpp Value a(kArrayType); Document::AllocatorType& allocator = document.GetAllocator(); @@ -368,7 +368,7 @@ for (int i = 5; i <= 10; i++) // Fluent interface a.PushBack("Lua", allocator).PushBack("Mio", allocator); -``` +~~~~~~~~~~ Differs from STL, `PushBack()`/`PopBack()` returns the array reference itself. This is called fluent interface. @@ -382,16 +382,16 @@ Object is a collection of key-value pairs. Each key must be a string value. The Here is an example. -```cpp +~~~~~~~~~~cpp Value contact(kObejct); contact.AddMember("name", "Milo", document.GetAllocator()); contact.AddMember("married", true, document.GetAllocator()); -``` +~~~~~~~~~~ ### Deep Copy Value If we really need to copy a DOM tree, we can use two APIs for deep copy: constructor with allocator, and `CopyFrom()`. -```cpp +~~~~~~~~~~cpp Document d; Document::AllocatorType& a = d.GetAllocator(); Value v1("foo"); @@ -406,19 +406,19 @@ v2.CopyFrom(d, a); // copy whole document to v2 assert(d.IsArray() && d.Size() == 2); // d untouched v1.SetObject().AddMember( "array", v2, a ); d.PushBack(v1,a); -``` +~~~~~~~~~~ ### Swap Values `Swap()` is also provided. -```cpp +~~~~~~~~~~cpp Value a(123); Value b("Hello"); a.Swap(b); assert(a.IsString()); assert(b.IsInt()); -``` +~~~~~~~~~~ Swapping two DOM trees is fast (constant time), despite the complexity of the tress. |