* Similar to [SAX](http://en.wikipedia.org/wiki/Simple_API_for_XML), RapidJSON provides a event sequential access parser API (`GenericReader`). It also provides a generator API (`GenericWriter`) which consumes the same set of events.
* Similar to [SAX](http://en.wikipedia.org/wiki/Simple_API_for_XML), RapidJSON provides a event sequential access parser API (`rapidjson::GenericReader`). It also provides a generator API (`rapidjson::Writer`) which consumes the same set of events.
* DOM (Document Object Model) style API
* DOM (Document Object Model) style API
* Similar to [DOM](http://en.wikipedia.org/wiki/Document_Object_Model) for HTML/XML, RapidJSON can parse JSON into a DOM representation (`GenericDocument`), for easy manipulation, and finally stringify back to JSON if needed.
* Similar to [DOM](http://en.wikipedia.org/wiki/Document_Object_Model) for HTML/XML, RapidJSON can parse JSON into a DOM representation (`rapidjson::GenericDocument`), for easy manipulation, and finally stringify back to JSON if needed.
* The DOM style API (`GenericDocument`) is actually implemented with SAX style API (`GenericReader`). SAX is faster but sometimes DOM is easier. Users can pick their choices according to scenarios.
* The DOM style API (`rapidjson::GenericDocument`) is actually implemented with SAX style API (`rapidjson::GenericReader`). SAX is faster but sometimes DOM is easier. Users can pick their choices according to scenarios.
## DOM (Document)
## DOM (Document)
...
@@ -59,13 +59,13 @@
...
@@ -59,13 +59,13 @@
## SAX (Writer)
## SAX (Writer)
* Support PrettyWriter for adding newlines and indentations.
* Support `rapidjson::PrettyWriter` for adding newlines and indentations.
* Support custom precision for floating point values.
* Support custom precision for floating point values.
## Stream
## Stream
* Support `GenericStringBuffer` for storing the output JSON as string.
* Support `rapidjson::GenericStringBuffer` for storing the output JSON as string.
* Support `FileReadStream`/`FileWriteStream` for input/output `FILE` object.
* Support `rapidjson::FileReadStream`/`rapidjson::FileWriteStream` for input/output `FILE` object.
In RapidJSON, `Stream` is a concept for reading/writing JSON. Here we first show how to use streams provided. And then see how to create a custom streams.
In RapidJSON, `rapidjson::Stream` is a concept for reading/writing JSON. Here we first show how to use streams provided. And then see how to create a custom streams.
## Memory Streams
## Memory Streams
...
@@ -10,7 +10,7 @@ Memory streams store JSON in memory.
...
@@ -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`.
`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"
#include "rapidjson/document.h" // will include "rapidjson/rapidjson.h"
using namespace rapidjson;
using namespace rapidjson;
...
@@ -21,16 +21,16 @@ StringStream s(json);
...
@@ -21,16 +21,16 @@ StringStream s(json);
Document d;
Document d;
d.ParseStream(s);
d.ParseStream(s);
```
~~~~~~~~~~
Since this is very common usage, `Document::Parse(const char*)` is provided to do exactly the same as above:
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]";
const char json[] = "[1, 2, 3, 4]";
Document d;
Document d;
d.Parse(json);
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.
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
...
@@ -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.
`StringBuffer` is a simple output stream. It allocates a memory buffer for writing the whole JSON. Use `GetString()` to obtain the buffer.
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.
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 buffer1(0, 1024); // Use its allocator, initial size = 1024
StringBuffer buffer2(allocator, 1024);
StringBuffer buffer2(allocator, 1024);
```
~~~~~~~~~~
By default, `StringBuffer` will instantiate an internal allocator.
By default, `StringBuffer` will instantiate an internal allocator.
...
@@ -69,10 +69,12 @@ However, if the JSON is big, or memory is limited, you can use `FileReadStream`.
...
@@ -69,10 +69,12 @@ 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.
`FileReadStream` reads the file via a `FILE` pointer. And user need to provide a buffer.
```cpp
~~~~~~~~~~cpp
#include "rapidjson/filereadstream.h"
#include "rapidjson/filereadstream.h"
#include <cstdio>
#include <cstdio>
using namespace rapidjson;
FILE* fp = fopen("big.json", "rb"); // non-Windows use "r"
FILE* fp = fopen("big.json", "rb"); // non-Windows use "r"
char readBuffer[65536];
char readBuffer[65536];
...
@@ -82,7 +84,7 @@ Document d;
...
@@ -82,7 +84,7 @@ Document d;
d.ParseStream(is);
d.ParseStream(is);
fclose(fp);
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.
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,10 +94,12 @@ Apart from reading file, user can also use `FileReadStream` to read `stdin`.
...
@@ -92,10 +94,12 @@ Apart from reading file, user can also use `FileReadStream` to read `stdin`.
`FileWriteStream` is buffered output stream. Its usage is very similar to `FileReadStream`.
`FileWriteStream` is buffered output stream. Its usage is very similar to `FileReadStream`.
@@ -129,7 +133,7 @@ Note that, these encoded streams can be applied to streams other than file. For
...
@@ -129,7 +133,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.
`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.
d.Accept(writer); // This generates UTF32-LE file from UTF-8 in memory
d.Accept(writer); // This generates UTF32-LE file from UTF-8 in memory
fclose(fp);
fclose(fp);
```
~~~~~~~~~~
### AutoUTFInputStream
### AutoUTFInputStream
...
@@ -182,7 +186,7 @@ Sometimes an application may want to handle all supported JSON encoding. `AutoUT
...
@@ -182,7 +186,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:
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:
d.ParseStream<0, AutoUTF<unsigned> >(eis); // This parses any UTF file into UTF-8 in memory
d.ParseStream<0, AutoUTF<unsigned> >(eis); // This parses any UTF file into UTF-8 in memory
fclose(fp);
fclose(fp);
```
~~~~~~~~~~
When specifying the encoding of stream, uses `AutoUTF<CharType>` as in `ParseStream()` above.
When specifying the encoding of stream, uses `AutoUTF<CharType>` as in `ParseStream()` above.
...
@@ -211,7 +215,9 @@ You can obtain the type of UTF via `UTFType GetType()`. And check whether a BOM
...
@@ -211,7 +215,9 @@ 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.
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.
`AutoUTFInputStream` and `AutoUTFOutputStream` is more convenient than `EncodedInputStream` and `EncodedOutputStream`. They just incur a little bit runtime overheads.
`AutoUTFInputStream` and `AutoUTFOutputStream` is more convenient than `EncodedInputStream` and `EncodedOutputStream`. They just incur a little bit runtime overheads.
...
@@ -232,7 +238,7 @@ In addition to memory/file streams, user can create their own stream classes whi
...
@@ -232,7 +238,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`:
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 {
concept Stream {
typename Ch; //!< Character type of the stream.
typename Ch; //!< Character type of the stream.
...
@@ -261,7 +267,7 @@ concept Stream {
...
@@ -261,7 +267,7 @@ concept Stream {
//! \return Number of characters written.
//! \return Number of characters written.
size_t PutEnd(Ch* begin);
size_t PutEnd(Ch* begin);
}
}
```
~~~~~~~~~~
For input stream, they must implement `Peek()`, `Take()` and `Tell()`.
For input stream, they must implement `Peek()`, `Take()` and `Tell()`.
For output stream, they must implement `Put()` and `Flush()`.
For output stream, they must implement `Put()` and `Flush()`.
...
@@ -271,7 +277,7 @@ There are two special interface, `PutBegin()` and `PutEnd()`, which are only for
...
@@ -271,7 +277,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.
The following example is a wrapper of `std::istream`, which only implements 3 functions.
```cpp
~~~~~~~~~~cpp
class IStreamWrapper {
class IStreamWrapper {
public:
public:
typedef char Ch;
typedef char Ch;
...
@@ -302,18 +308,18 @@ private:
...
@@ -302,18 +308,18 @@ private:
std::istream& is_;
std::istream& is_;
};
};
```
~~~~~~~~~~
User can use it to wrap instances of `std::stringstream`, `std::ifstream`.
User can use it to wrap instances of `std::stringstream`, `std::ifstream`.
```cpp
~~~~~~~~~~cpp
const char* json = "[1,2,3,4]";
const char* json = "[1,2,3,4]";
std::stringstream ss(json);
std::stringstream ss(json);
IStreamWrapper is(ss);
IStreamWrapper is(ss);
Document d;
Document d;
d.Parse(is);
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.
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 +327,7 @@ Note that, this implementation may not be as efficient as RapidJSON's memory or
...
@@ -321,7 +327,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.
The following example is a wrapper of `std::istream`, which only implements 2 functions.
```cpp
~~~~~~~~~~cpp
class OStreamWrapper {
class OStreamWrapper {
public:
public:
typedef char Ch;
typedef char Ch;
...
@@ -344,11 +350,11 @@ private:
...
@@ -344,11 +350,11 @@ private:
std::ostream& os_;
std::ostream& os_;
};
};
```
~~~~~~~~~~
User can use it to wrap instances of `std::stringstream`, `std::ofstream`.
User can use it to wrap instances of `std::stringstream`, `std::ofstream`.
```cpp
~~~~~~~~~~cpp
Document d;
Document d;
// ...
// ...
...
@@ -357,7 +363,7 @@ OSStreamWrapper os(ss);
...
@@ -357,7 +363,7 @@ OSStreamWrapper os(ss);
Writer<OStreamWrapper> writer(os);
Writer<OStreamWrapper> writer(os);
d.Accept(writer);
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.
Note that, this implementation may not be as efficient as RapidJSON's memory or file streams, due to internal overheads of the standard library.
\tparam Encoding encoding for both parsing and string storage.
\tparam Encoding encoding for both parsing and string storage.
\tparam Allocator allocator for allocating memory for the DOM, and the stack during parsing.
\tparam Allocator allocator for allocating memory for the DOM, and the stack during parsing.
\warning Although GenericDocument inherits from GenericValue, the API does \b not provide any virtual functions, especially no virtual destructors. To avoid memory leaks, do not \c delete a GenericDocument object via a pointer to a GenericValue.
