Description
Because of the name, the finalize helper might easily be misunderstood as "finishing" a document being constructed, whereas it actually destructively steals the constructed document and returns it, leaving the builder with empty state.
Consider the following example:
using bsoncxx::builder::stream::document;
|
using bsoncxx::builder::stream::finalize;
|
|
|
document one;
|
one << "key" << "value";
|
std::cout << bsoncxx::to_json(one.view()) << std::endl;
|
|
|
document two;
|
two << "key" << "value" << finalize;
|
std::cout << bsoncxx::to_json(two.view()) << std::endl;
|
The result is:
{
|
"key" : "value"
|
}
|
{
|
|
|
}
|
If we rename finalize to something more self-documenting (and alarming) like steal_document, the API would be harder to mistakenly misuse.
For example:
document two;
|
two << "key" << "value" << steal_document;
|
That is obviously a mistake. It also makes clear what assignment is doing:
document three;
|
auto doc = three << "key" << "value" << steal_document;
|