add GenericDocument<>::Swap

[pah]

See #368.

[miloyip]

I suggest not to include algorithm for swap. As that header is quite big and may increase compilation overhead. How about creating one internally?

[Kosta-Github]

Why not using lowercase "swap" for the method name? In that case it could work hand in hand with std::swap() and std::swap(doc1, doc2) would automatically pick up the optimized implementation; otherwise std::swap() would do the unoptimized create-copy-temp-from-b, copy-a-to-b, copy-temp-to-a thing...

[pah]

@miloyip Ok, I'll try to have a look.

@Kosta-Github Providing a lower-case swap member function would break the consistency of the RapidJSON API function naming conventions. Instead, we (or even users) could provide a lower-case swap in the rapidjson namespace, which should achieve the same thing.

[Kosta-Github]

Yeah, I am aware of the inconsistency but still think that easy/efficient interop with the STL is also worth to be considered.

Users most probably will not provide their own rapidjson::swap() function, because the usage of std::swap(doc1, doc2) already works out-of-the-box, but unfortunately with less-than-optimal performance.

[pah]

@miloyip: I have now added a new helper function internal::Swap(), which avoids the dependency on the <algorithm> header.

@Kosta-Github: On my platform, std::swap doesn't work out of the box for GenericDocument/GenericValue as both classes are not copyable by default. If it works on your platform, then probably due to the enabled C++11 move support. In the latter case, the default swap is nearly as efficient than the explicit one.

We could add an "inline friend" function to GenericValue/GenericDocument to enable the common swap idiom:

    // add to GenericValue, GenericDocument (analogously)
    friend inline void swap(GenericValue& a, GenericValue& b) RAPIDJSON_NOEXCEPT
       { a.Swap(b); }

   // enables common pattern:
   using std::swap;
   swap(v1, v2); // calls GenericValue's friend through argument-dependent lookup

@miloyip, what do you think?

[miloyip]

@pah I think both changes are OK for me.

[pah]

I've just added the two free-standing friend swap functions.

[miloyip]

Brilliant~