From 50660c093d7a483642fca27e5adfafe74fc601d0 Mon Sep 17 00:00:00 2001 From: Mateusz Loskot Date: Thu, 2 Jul 2015 14:00:52 +0200 Subject: [PATCH 1/2] Add to FAQ: How to insert a document node into another document? Closes #366 --- doc/faq.md | 39 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 39 insertions(+) diff --git a/doc/faq.md b/doc/faq.md index 093e8e7b3..da0d39ed0 100644 --- a/doc/faq.md +++ b/doc/faq.md @@ -117,6 +117,45 @@ d.Swap(Value(kObjectType).Move()) ``` +9. How to insert a document node into another document? + +Let's take the following two DOM trees represented as JSON documents: + ``` + Document person; + person.Parse("{\"person\":{\"name\":{\"first\":\"Adam\",\"last\":\"Thomas\"}}}"); + + Document address; + address.Parse("{\"address\":{\"city\":\"Moscow\",\"street\":\"Quiet\"}}"); + ``` +Let's assume we want to merge them in such way that the whole `address` document becomes a node of the `person`: + ``` + { "person": { + "name": { "first": "Adam", "last": "Thomas" }, + "address": { "city": "Moscow", "street": "Quiet" } + } + } + ``` + +The most important requirement to take care of document and value life-cycle as well as consistent memory managent using the right allocator during the value transfer. + +* Simple yet most efficient way to achieve that is to modify the `address` definition above to initialize it with allocator of the `person` document, then we just add the root nenber of the value: + ``` + Documnet address(person.GetAllocator()); + ... + person["person"].AddMember("address", address["address"], person.GetAllocator()); + ``` +Alternatively, if we don't want to explicitly refer to the root value of `address` by name, we can refer to it via iterator: + ``` + auto addressRoot = address.MemberBegin(); + person["person"].AddMember(addressRoot->name, addressRoot->value, person.GetAllocator()); + ``` + +* Second way is to deep-clone the value from the address document: + ``` + Value addressValue = Value(address["address"], person.GetAllocator()); + person["person"].AddMember("address", addressValue, person.GetAllocator()); + ``` + ## Document/Value (DOM) 1. What is move semantics? Why? From 5ac04cb0123104c3cd5afc0bec6941ae149b2725 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Mateusz=20=C5=81oskot?= Date: Thu, 2 Jul 2015 14:05:30 +0200 Subject: [PATCH 2/2] Correct formatting of FAQ 8 and 9 --- doc/faq.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/doc/faq.md b/doc/faq.md index da0d39ed0..1ff6e088e 100644 --- a/doc/faq.md +++ b/doc/faq.md @@ -104,7 +104,7 @@ 8. How to clear-and-minimize a document or value? -* Call one of the `SetXXX()` methods - they call destructor which deallocates DOM data: + Call one of the `SetXXX()` methods - they call destructor which deallocates DOM data: ``` Document d; @@ -112,14 +112,14 @@ d.SetObject(); // clear and minimize ``` -* Alternatively, use equivalent of the [C++ swap with temporary idiom](https://en.wikibooks.org/wiki/More_C%2B%2B_Idioms/Clear-and-minimize): + Alternatively, use equivalent of the [C++ swap with temporary idiom](https://en.wikibooks.org/wiki/More_C%2B%2B_Idioms/Clear-and-minimize): ``` d.Swap(Value(kObjectType).Move()) ``` 9. How to insert a document node into another document? -Let's take the following two DOM trees represented as JSON documents: + Let's take the following two DOM trees represented as JSON documents: ``` Document person; person.Parse("{\"person\":{\"name\":{\"first\":\"Adam\",\"last\":\"Thomas\"}}}"); @@ -127,7 +127,7 @@ Let's take the following two DOM trees represented as JSON documents: Document address; address.Parse("{\"address\":{\"city\":\"Moscow\",\"street\":\"Quiet\"}}"); ``` -Let's assume we want to merge them in such way that the whole `address` document becomes a node of the `person`: + Let's assume we want to merge them in such way that the whole `address` document becomes a node of the `person`: ``` { "person": { "name": { "first": "Adam", "last": "Thomas" }, @@ -136,9 +136,9 @@ Let's assume we want to merge them in such way that the whole `address` document } ``` -The most important requirement to take care of document and value life-cycle as well as consistent memory managent using the right allocator during the value transfer. + The most important requirement to take care of document and value life-cycle as well as consistent memory managent using the right allocator during the value transfer. -* Simple yet most efficient way to achieve that is to modify the `address` definition above to initialize it with allocator of the `person` document, then we just add the root nenber of the value: + Simple yet most efficient way to achieve that is to modify the `address` definition above to initialize it with allocator of the `person` document, then we just add the root nenber of the value: ``` Documnet address(person.GetAllocator()); ... @@ -150,7 +150,7 @@ Alternatively, if we don't want to explicitly refer to the root value of `addres person["person"].AddMember(addressRoot->name, addressRoot->value, person.GetAllocator()); ``` -* Second way is to deep-clone the value from the address document: + Second way is to deep-clone the value from the address document: ``` Value addressValue = Value(address["address"], person.GetAllocator()); person["person"].AddMember("address", addressValue, person.GetAllocator());