tutorial.md 21.5 KB
Newer Older
miloyip's avatar
miloyip committed
1
# Tutorial
miloyip's avatar
miloyip committed
2

3
This tutorial introduces the basics of the Document Object Model(DOM) API.
miloyip's avatar
miloyip committed
4

5
As shown in [Usage at a glance](@ref index), JSON can be parsed into a DOM, and then the DOM can be queried and modified easily, and finally be converted back to JSON.
miloyip's avatar
miloyip committed
6

7 8 9
[TOC]

# Value & Document {#ValueDocument}
miloyip's avatar
miloyip committed
10

Milo Yip's avatar
Milo Yip committed
11
Each JSON value is stored in a type called `Value`. A `Document`, representing the DOM, contains the root `Value` of the DOM tree. All public types and functions of RapidJSON are defined in the `rapidjson` namespace.
miloyip's avatar
miloyip committed
12

13
# Query Value {#QueryValue}
miloyip's avatar
miloyip committed
14

15
In this section, we will use excerpt of `example/tutorial/tutorial.cpp`.
miloyip's avatar
miloyip committed
16

17
Assume we have the following JSON stored in a C string (`const char* json`):
Milo Yip's avatar
Milo Yip committed
18
~~~~~~~~~~js
miloyip's avatar
miloyip committed
19 20 21 22 23 24 25 26 27
{
    "hello": "world",
    "t": true ,
    "f": false,
    "n": null,
    "i": 123,
    "pi": 3.1416,
    "a": [1, 2, 3, 4]
}
Milo Yip's avatar
Milo Yip committed
28
~~~~~~~~~~
miloyip's avatar
miloyip committed
29

Milo Yip's avatar
Milo Yip committed
30
Parse it into a `Document`:
Milo Yip's avatar
Milo Yip committed
31
~~~~~~~~~~cpp
miloyip's avatar
miloyip committed
32 33 34 35 36 37 38
#include "rapidjson/document.h"

using namespace rapidjson;

// ...
Document document;
document.Parse(json);
Milo Yip's avatar
Milo Yip committed
39
~~~~~~~~~~
miloyip's avatar
miloyip committed
40

Milo Yip's avatar
Milo Yip committed
41
The JSON is now parsed into `document` as a *DOM tree*:
miloyip's avatar
miloyip committed
42

43
![DOM in the tutorial](diagram/tutorial.png)
44

Milo Yip's avatar
Milo Yip committed
45
Since the update to RFC 7159, the root of a conforming JSON document can be any JSON value.  In earlier RFC 4627, only objects or arrays were allowed as root values. In this case, the root is an object.
Milo Yip's avatar
Milo Yip committed
46
~~~~~~~~~~cpp
miloyip's avatar
miloyip committed
47
assert(document.IsObject());
Milo Yip's avatar
Milo Yip committed
48
~~~~~~~~~~
miloyip's avatar
miloyip committed
49

Milo Yip's avatar
Milo Yip committed
50
Let's 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.
Milo Yip's avatar
Milo Yip committed
51
~~~~~~~~~~cpp
miloyip's avatar
miloyip committed
52 53 54
assert(document.HasMember("hello"));
assert(document["hello"].IsString());
printf("hello = %s\n", document["hello"].GetString());
Milo Yip's avatar
Milo Yip committed
55
~~~~~~~~~~
miloyip's avatar
miloyip committed
56

Milo Yip's avatar
Milo Yip committed
57
~~~~~~~~~~
58
hello = world
Milo Yip's avatar
Milo Yip committed
59
~~~~~~~~~~
60

miloyip's avatar
miloyip committed
61
JSON true/false values are represented as `bool`.
Milo Yip's avatar
Milo Yip committed
62
~~~~~~~~~~cpp
miloyip's avatar
miloyip committed
63 64
assert(document["t"].IsBool());
printf("t = %s\n", document["t"].GetBool() ? "true" : "false");
Milo Yip's avatar
Milo Yip committed
65
~~~~~~~~~~
miloyip's avatar
miloyip committed
66

Milo Yip's avatar
Milo Yip committed
67
~~~~~~~~~~
68
t = true
Milo Yip's avatar
Milo Yip committed
69
~~~~~~~~~~
70

71
JSON null can be queryed with `IsNull()`.
Milo Yip's avatar
Milo Yip committed
72
~~~~~~~~~~cpp
miloyip's avatar
miloyip committed
73
printf("n = %s\n", document["n"].IsNull() ? "null" : "?");
Milo Yip's avatar
Milo Yip committed
74
~~~~~~~~~~
miloyip's avatar
miloyip committed
75

Milo Yip's avatar
Milo Yip committed
76
~~~~~~~~~~
77
n = null
Milo Yip's avatar
Milo Yip committed
78
~~~~~~~~~~
79

miloyip's avatar
miloyip committed
80 81
JSON number type represents all numeric values. However, C++ needs more specific type for manipulation.

Milo Yip's avatar
Milo Yip committed
82
~~~~~~~~~~cpp
miloyip's avatar
miloyip committed
83 84 85 86 87 88 89 90 91 92
assert(document["i"].IsNumber());

// In this case, IsUint()/IsInt64()/IsUInt64() also return true.
assert(document["i"].IsInt());          
printf("i = %d\n", document["i"].GetInt());
// Alternative (int)document["i"]

assert(document["pi"].IsNumber());
assert(document["pi"].IsDouble());
printf("pi = %g\n", document["pi"].GetDouble());
Milo Yip's avatar
Milo Yip committed
93
~~~~~~~~~~
miloyip's avatar
miloyip committed
94

Milo Yip's avatar
Milo Yip committed
95
~~~~~~~~~~
96 97
i = 123
pi = 3.1416
Milo Yip's avatar
Milo Yip committed
98
~~~~~~~~~~
99 100

JSON array contains a number of elements.
Milo Yip's avatar
Milo Yip committed
101
~~~~~~~~~~cpp
miloyip's avatar
miloyip committed
102 103 104 105 106
// 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());
Milo Yip's avatar
Milo Yip committed
107
~~~~~~~~~~
miloyip's avatar
miloyip committed
108

Milo Yip's avatar
Milo Yip committed
109
~~~~~~~~~~
110 111 112 113
a[0] = 1
a[1] = 2
a[2] = 3
a[3] = 4
Milo Yip's avatar
Milo Yip committed
114
~~~~~~~~~~
miloyip's avatar
miloyip committed
115

116 117
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.

118
In the following sections we discuss details about querying individual types.
119

120
## Query Array {#QueryArray}
121

122
By default, `SizeType` is typedef of `unsigned`. In most systems, an array is limited to store up to 2^32-1 elements.
123

124
You may access the elements in an array by integer literal, for example, `a[0]`, `a[1]`, `a[2]`.
125

126
Array is similar to `std::vector`: instead of using indices, you may also use iterator to access all the elements.
Milo Yip's avatar
Milo Yip committed
127
~~~~~~~~~~cpp
128 129
for (Value::ConstValueIterator itr = a.Begin(); itr != a.End(); ++itr)
    printf("%d ", itr->GetInt());
Milo Yip's avatar
Milo Yip committed
130
~~~~~~~~~~
131

132
And other familiar query functions:
133 134 135
* `SizeType Capacity() const`
* `bool Empty() const`

Milo Yip's avatar
Milo Yip committed
136 137 138 139 140 141 142 143 144
### 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());
~~~~~~~~~~

145
## Query Object {#QueryObject}
146

147
Similar to Array, we can access all object members by iterator:
148

Milo Yip's avatar
Milo Yip committed
149
~~~~~~~~~~cpp
150 151 152 153 154 155 156 157 158
static const char* kTypeNames[] = 
    { "Null", "False", "True", "Object", "Array", "String", "Number" };

for (Value::ConstMemberIterator itr = document.MemberBegin();
    itr != document.MemberEnd(); ++itr)
{
    printf("Type of member %s is %s\n",
        itr->name.GetString(), kTypeNames[itr->value.GetType()]);
}
Milo Yip's avatar
Milo Yip committed
159
~~~~~~~~~~
miloyip's avatar
miloyip committed
160

Milo Yip's avatar
Milo Yip committed
161
~~~~~~~~~~
162 163 164 165 166 167 168
Type of member hello is String
Type of member t is True
Type of member f is False
Type of member n is Null
Type of member i is Number
Type of member pi is Number
Type of member a is Array
Milo Yip's avatar
Milo Yip committed
169
~~~~~~~~~~
170 171 172 173 174

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:

Milo Yip's avatar
Milo Yip committed
175
~~~~~~~~~~cpp
176
Value::ConstMemberIterator itr = document.FindMember("hello");
Milo Yip's avatar
Milo Yip committed
177
if (itr != document.MemberEnd())
Milo Yip's avatar
Milo Yip committed
178
    printf("%s\n", itr->value.GetString());
Milo Yip's avatar
Milo Yip committed
179
~~~~~~~~~~
180

Milo Yip's avatar
Milo Yip committed
181 182 183 184 185 186 187 188 189 190
### 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()]);
~~~~~~~~~~

191
## Querying Number {#QueryNumber}
192

193
JSON provides a single numerical type called Number. Number can be an integer or a real number. RFC 4627 says the range of Number is specified by the parser implementation.
194

195
As C++ provides several integer and floating point number types, the DOM tries to handle these with the widest possible range and good performance.
196

197
When a Number is parsed, it is stored in the DOM as one of the following types:
198 199

Type       | Description
Milo Yip's avatar
Milo Yip committed
200
-----------|---------------------------------------
201 202 203 204 205 206
`unsigned` | 32-bit unsigned integer
`int`      | 32-bit signed integer
`uint64_t` | 64-bit unsigned integer
`int64_t`  | 64-bit signed integer
`double`   | 64-bit double precision floating point

207
When querying a number, you can check whether the number can be obtained as the target type:
208

Milo Yip's avatar
Milo Yip committed
209 210 211 212
Checking          | Obtaining
------------------|---------------------
`bool IsNumber()` | N/A
`bool IsUint()`   | `unsigned GetUint()`
Milo Yip's avatar
Milo Yip committed
213
`bool IsInt()`    | `int GetInt()`
214
`bool IsUint64()` | `uint64_t GetUint64()`
Milo Yip's avatar
Milo Yip committed
215
`bool IsInt64()`  | `int64_t GetInt64()`
Milo Yip's avatar
Milo Yip committed
216
`bool IsDouble()` | `double GetDouble()`
217

218
Note that, an integer value may be obtained in various ways without conversion. For example, A value `x` containing 123 will make `x.IsInt() == x.IsUint() == x.IsInt64() == x.IsUint64() == true`. But a value `y` containing -3000000000 will only make `x.IsInt64() == true`.
219

220
When obtaining the numeric values, `GetDouble()` will convert internal integer representation to a `double`. Note that, `int` and `unsigned` can be safely converted to `double`, but `int64_t` and `uint64_t` may lose precision (since mantissa of `double` is only 52-bits).
221

222
## Query String {#QueryString}
223 224 225

In addition to `GetString()`, the `Value` class also contains `GetStringLength()`. Here explains why.

226
According to RFC 4627, JSON strings can contain Unicode character `U+0000`, which must be escaped as `"\u0000"`. The problem is that, C/C++ often uses null-terminated string, which treats ``\0'` as the terminator symbol.
227

228
To conform RFC 4627, RapidJSON supports string containing `U+0000`. If you need to handle this, you can use `GetStringLength()` to obtain the correct string length.
229

Milo Yip's avatar
Milo Yip committed
230
For example, after parsing a the following JSON to `Document d`:
231

Milo Yip's avatar
Milo Yip committed
232
~~~~~~~~~~js
233
{ "s" :  "a\u0000b" }
Milo Yip's avatar
Milo Yip committed
234
~~~~~~~~~~
235 236 237 238 239 240
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:

Milo Yip's avatar
Milo Yip committed
241
~~~~~~~~~~cpp
242
string(const char* s, size_t count);
Milo Yip's avatar
Milo Yip committed
243
~~~~~~~~~~
244 245 246

which accepts the length of string as parameter. This constructor supports storing null character within the string, and should also provide better performance.

247 248 249 250 251 252 253 254 255 256 257
## Comparing values

You can use `==` and `!=` to compare values. Two values are equal if and only if they are have same type and contents. You can also compare values with primitive types. Here is an example.

~~~~~~~~~~cpp
if (document["hello"] == document["n"]) /*...*/;    // Compare values
if (document["hello"] == "world") /*...*/;          // Compare value with literal string
if (document["i"] != 123) /*...*/;                  // Compare with integers
if (document["pi"] != 3.14) /*...*/;                // Compare with double.
~~~~~~~~~~

Milo Yip's avatar
Milo Yip committed
258
Array/object compares their elements/members in order. They are equal if and only if their whole subtrees are equal.
259 260 261

Note that, currently if an object contains duplicated named member, comparing equality with any object is always `false`.

262
# Create/Modify Values {#CreateModifyValues}
miloyip's avatar
miloyip committed
263

264 265
There are several ways to create values. After a DOM tree is created and/or modified, it can be saved as JSON again using `Writer`.

266
## Change Value Type {#ChangeValueType}
267 268
When creating a Value or Document by default constructor, its type is Null. To change its type, call `SetXXX()` or assignment operator, for example:

Milo Yip's avatar
Milo Yip committed
269
~~~~~~~~~~cpp
270 271 272 273 274 275
Document d; // Null
d.SetObject();

Value v;    // Null
v.SetInt(10);
v = 10;     // Shortcut, same as above
Milo Yip's avatar
Milo Yip committed
276
~~~~~~~~~~
277 278 279 280

### Overloaded Constructors
There are also overloaded constructors for several types:

Milo Yip's avatar
Milo Yip committed
281
~~~~~~~~~~cpp
282 283 284 285
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)
Milo Yip's avatar
Milo Yip committed
286
~~~~~~~~~~
287 288 289

To create empty object or array, you may use `SetObject()`/`SetArray()` after default constructor, or using the `Value(Type)` in one shot:

Milo Yip's avatar
Milo Yip committed
290
~~~~~~~~~~cpp
291 292
Value o(kObjectType);
Value a(kArrayType);
Milo Yip's avatar
Milo Yip committed
293
~~~~~~~~~~
294

295
## Move Semantics {#MoveSemantics}
Milo Yip's avatar
Milo Yip committed
296

297 298
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,

Milo Yip's avatar
Milo Yip committed
299
~~~~~~~~~~cpp
300 301 302
Value a(123);
Value b(456);
b = a;         // a becomes a Null value, b becomes number 123.
Milo Yip's avatar
Milo Yip committed
303
~~~~~~~~~~
304

305
![Assignment with move semantics.](diagram/move1.png)
306 307 308 309 310

Why? What is the advantage of this semantics?

The simple answer is performance. For fixed size JSON types (Number, True, False, Null), copying them is fast and easy. However, For variable size JSON types (String, Array, Object), copying them will incur a lot of overheads. And these overheads are often unnoticed. Especially when we need to create temporary object, copy it to another variable, and then destruct it.

311
For example, if normal *copy* semantics was used:
312

Milo Yip's avatar
Milo Yip committed
313
~~~~~~~~~~cpp
314
Document d;
315 316 317 318 319
Value o(kObjectType);
{
    Value contacts(kArrayType);
    // adding elements to contacts array.
    // ...
320
    o.AddMember("contacts", contacts, d.GetAllocator());  // deep clone contacts (may be with lots of allocations)
321 322
    // destruct contacts.
}
Milo Yip's avatar
Milo Yip committed
323
~~~~~~~~~~
324

325
![Copy semantics makes a lots of copy operations.](diagram/move2.png)
326 327

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.
328 329 330

There are solutions to prevent actual copying these data, such as reference counting and garbage collection(GC).

331
To make RapidJSON simple and fast, we chose to use *move* semantics for assignment. It is similar to `std::auto_ptr` which transfer ownership during assignment. Move is much faster and simpler, it just destructs the original value, `memcpy()` the source to destination, and finally sets the source as Null type.
332

333
So, with move semantics, the above example becomes:
334

Milo Yip's avatar
Milo Yip committed
335
~~~~~~~~~~cpp
336
Document d;
337 338 339 340
Value o(kObjectType);
{
    Value contacts(kArrayType);
    // adding elements to contacts array.
341
    o.AddMember("contacts", contacts, d.GetAllocator());  // just memcpy() of contacts itself to the value of new member (16 bytes)
342 343
    // contacts became Null here. Its destruction is trivial.
}
Milo Yip's avatar
Milo Yip committed
344
~~~~~~~~~~
345

346
![Move semantics makes no copying.](diagram/move3.png)
347

Milo Yip's avatar
Milo Yip committed
348
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()`.
349

350 351 352 353 354 355
### Move semantics and temporary values {#TemporaryValues}

Sometimes, it is convenient to construct a Value in place, before passing it to one of the "moving" functions, like `PushBack()` or `AddMember()`.  As temporary objects can't be converted to proper Value references, the convenience function `Move()` is available:

~~~~~~~~~~cpp
Value a(kArrayType);
Milo Yip's avatar
Milo Yip committed
356 357 358 359
Document::AllocatorType& allocator = document.GetAllocator();
// a.PushBack(Value(42), allocator);       // will not compile
a.PushBack(Value().SetInt(42), allocator); // fluent API
a.PushBack(Value(42).Move(), allocator);   // same as above
360 361
~~~~~~~~~~

362
## Create String {#CreateString}
363
RapidJSON provides two strategies for storing string.
364 365 366 367

1. copy-string: allocates a buffer, and then copy the source data into it.
2. const-string: simply store a pointer of string.

368
Copy-string is always safe because it owns a copy of the data. Const-string can be used for storing a string literal, and for in-situ parsing which will be mentioned in the DOM section.
369

370
To make memory allocation customizable, RapidJSON requires users to pass an instance of allocator, whenever an operation may require allocation. This design is needed to prevent storing a allocator (or Document) pointer per Value.
371

372
Therefore, when we assign a copy-string, we call this overloaded `SetString()` with allocator:
373

Milo Yip's avatar
Milo Yip committed
374
~~~~~~~~~~cpp
375 376 377 378 379 380 381
Document document;
Value author;
char buffer[10];
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
Milo Yip's avatar
Milo Yip committed
382
~~~~~~~~~~
383

384
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.
385

386
Besides, the above `SetString()` requires length. This can handle null characters within a string. There is another `SetString()` overloaded function without the length parameter. And it assumes the input is null-terminated and calls a `strlen()`-like function to obtain the length.
387

388
Finally, for a string literal or string with a safe life-cycle one can use the const-string version of `SetString()`, which lacks an allocator parameter.  For string literals (or constant character arrays), simply passing the literal as parameter is safe and efficient:
389

Milo Yip's avatar
Milo Yip committed
390
~~~~~~~~~~cpp
391
Value s;
392
s.SetString("rapidjson");    // can contain null character, length derived at compile time
393
s = "rapidjson";             // shortcut, same as above
Milo Yip's avatar
Milo Yip committed
394
~~~~~~~~~~
395

396
For a character pointer, RapidJSON requires it to be marked as safe before using it without copying. This can be achieved by using the `StringRef` function:
397 398 399 400 401 402 403 404 405 406 407 408 409

~~~~~~~~~cpp
const char * cstr = getenv("USER");
size_t cstr_len = ...;                 // in case length is available
Value s;
// s.SetString(cstr);                  // will not compile
s.SetString(StringRef(cstr));          // ok, assume safe lifetime, null-terminated
s = StringRef(cstr);                   // shortcut, same as above
s.SetString(StringRef(cstr,cstr_len)); // faster, can contain null character
s = StringRef(cstr,cstr_len);          // shortcut, same as above

~~~~~~~~~

410
## Modify Array {#ModifyArray}
411
Value with array type provides an API similar to `std::vector`.
412 413 414 415 416 417

* `Clear()`
* `Reserve(SizeType, Allocator&)`
* `Value& PushBack(Value&, Allocator&)`
* `template <typename T> GenericValue& PushBack(T, Allocator&)`
* `Value& PopBack()`
418 419
* `ValueIterator Erase(ConstValueIterator pos)`
* `ValueIterator Erase(ConstValueIterator first, ConstValueIterator last)`
420

421
Note that, `Reserve(...)` and `PushBack(...)` may allocate memory for the array elements, therefore requiring an allocator.
422 423 424

Here is an example of `PushBack()`:

Milo Yip's avatar
Milo Yip committed
425
~~~~~~~~~~cpp
426 427 428 429
Value a(kArrayType);
Document::AllocatorType& allocator = document.GetAllocator();

for (int i = 5; i <= 10; i++)
430
    a.PushBack(i, allocator);   // allocator is needed for potential realloc().
431 432 433

// Fluent interface
a.PushBack("Lua", allocator).PushBack("Mio", allocator);
Milo Yip's avatar
Milo Yip committed
434
~~~~~~~~~~
435

436
This API differs from STL in that `PushBack()`/`PopBack()` return the array reference itself. This is called _fluent interface_.
437 438 439 440 441 442 443 444 445 446 447 448

If you want to add a non-constant string or a string without sufficient lifetime (see [Create String](#CreateString)) to the array, you need to create a string Value by using the copy-string API.  To avoid the need for an intermediate variable, you can use a [temporary value](#TemporaryValues) in place:

~~~~~~~~~~cpp
// in-place Value parameter
contact.PushBack(Value("copy", document.GetAllocator()).Move(), // copy string
                 document.GetAllocator());

// explicit parameters
Value val("key", document.GetAllocator()); // copy string
contact.PushBack(val, document.GetAllocator());
~~~~~~~~~~
449

450
## Modify Object {#ModifyObject}
451
The Object class is a collection of key-value pairs (members). Each key must be a string value. To modify an object, either add or remove members. The following API is for adding members:
452 453

* `Value& AddMember(Value&, Value&, Allocator& allocator)`
454 455
* `Value& AddMember(StringRefType, Value&, Allocator&)`
* `template <typename T> Value& AddMember(StringRefType, T value, Allocator&)`
456 457 458

Here is an example.

Milo Yip's avatar
Milo Yip committed
459
~~~~~~~~~~cpp
460
Value contact(kObject);
461 462
contact.AddMember("name", "Milo", document.GetAllocator());
contact.AddMember("married", true, document.GetAllocator());
463 464
~~~~~~~~~~

465
The name parameter with `StringRefType` is similar to the interface of the `SetString` function for string values. These overloads are used to avoid the need for copying the `name` string, since constant key names are very common in JSON objects.
466 467 468 469 470 471 472 473 474 475

If you need to create a name from a non-constant string or a string without sufficient lifetime (see [Create String](#CreateString)), you need to create a string Value by using the copy-string API.  To avoid the need for an intermediate variable, you can use a [temporary value](#TemporaryValues) in place:

~~~~~~~~~~cpp
// in-place Value parameter
contact.AddMember(Value("copy", document.GetAllocator()).Move(), // copy string
                  Value().Move(),                                // null value
                  document.GetAllocator());

// explicit parameters
Milo Yip's avatar
Milo Yip committed
476
Value key("key", document.GetAllocator()); // copy string name
477 478
Value val(42);                             // some value
contact.AddMember(key, val, document.GetAllocator());
Milo Yip's avatar
Milo Yip committed
479
~~~~~~~~~~
480

481 482 483 484 485 486 487 488
For removing members, there are several choices: 

* `bool RemoveMember(const Ch* name)`: Remove a member by search its name (linear time complexity).
* `bool RemoveMember(const Value& name)`: same as above but `name` is a Value.
* `MemberIterator RemoveMember(MemberIterator)`: Remove a member by iterator (_constant_ time complexity).
* `MemberIterator EraseMember(MemberIterator)`: similar to the above but it preserves order of members (linear time complexity).
* `MemberIterator EraseMember(MemberIterator first, MemberIterator last)`: remove a range of members, preserves order (linear time complexity).

Milo Yip's avatar
Milo Yip committed
489
`MemberIterator RemoveMember(MemberIterator)` uses a "move-last" trick to achieve constant time complexity. Basically the member at iterator is destructed, and then the last element is moved to that position. So the order of the remaining members are changed.
490

491
## Deep Copy Value {#DeepCopyValue}
Milo Yip's avatar
Milo Yip committed
492
If we really need to copy a DOM tree, we can use two APIs for deep copy: constructor with allocator, and `CopyFrom()`.
493

Milo Yip's avatar
Milo Yip committed
494
~~~~~~~~~~cpp
495 496 497 498 499
Document d;
Document::AllocatorType& a = d.GetAllocator();
Value v1("foo");
// Value v2(v1); // not allowed

Milo Yip's avatar
Milo Yip committed
500 501
Value v2(v1, a);                      // make a copy
assert(v1.IsString());                // v1 untouched
502
d.SetArray().PushBack(v1, a).PushBack(v2, a);
Milo Yip's avatar
Milo Yip committed
503
assert(v1.IsNull() && v2.IsNull());   // both moved to d
504

Milo Yip's avatar
Milo Yip committed
505 506
v2.CopyFrom(d, a);                    // copy whole document to v2
assert(d.IsArray() && d.Size() == 2); // d untouched
507 508
v1.SetObject().AddMember("array", v2, a);
d.PushBack(v1, a);
Milo Yip's avatar
Milo Yip committed
509
~~~~~~~~~~
miloyip's avatar
miloyip committed
510

511
## Swap Values {#SwapValues}
miloyip's avatar
miloyip committed
512

Milo Yip's avatar
Milo Yip committed
513 514
`Swap()` is also provided.

Milo Yip's avatar
Milo Yip committed
515
~~~~~~~~~~cpp
Milo Yip's avatar
Milo Yip committed
516 517 518 519 520
Value a(123);
Value b("Hello");
a.Swap(b);
assert(a.IsString());
assert(b.IsInt());
Milo Yip's avatar
Milo Yip committed
521
~~~~~~~~~~
Milo Yip's avatar
Milo Yip committed
522

523
Swapping two DOM trees is fast (constant time), despite the complexity of the trees.
Milo Yip's avatar
Milo Yip committed
524

525
# What's next {#WhatsNext}
miloyip's avatar
miloyip committed
526

Milo Yip's avatar
Milo Yip committed
527 528
This tutorial shows the basics of DOM tree query and manipulation. There are several important concepts in RapidJSON:

529 530 531 532 533 534
1. [Streams](doc/stream.md) are channels for reading/writing JSON, which can be a in-memory string, or file stream, etc. User can also create their streams.
2. [Encoding](doc/encoding.md) defines which character encoding is used in streams and memory. RapidJSON also provide Unicode conversion/validation internally.
3. [DOM](doc/dom.md)'s basics are already covered in this tutorial. Uncover more advanced features such as *in situ* parsing, other parsing options and advanced usages.
4. [SAX](doc/sax.md) is the foundation of parsing/generating facility in RapidJSON. Learn how to use `Reader`/`Writer` to implement even faster applications. Also try `PrettyWriter` to format the JSON.
5. [Performance](doc/performance.md) shows some in-house and third-party benchmarks.
6. [Internals](doc/internals.md) describes some internal designs and techniques of RapidJSON.
Milo Yip's avatar
Milo Yip committed
535

536
You may also refer to the [FAQ](doc/faq.md), API documentation, examples and unit tests.