Uploaded image for project: 'C++ Driver'
  1. C++ Driver
  2. CXX-973

Rename bsoncxx::builder::stream::finalize to extract

    XMLWordPrintableJSON

Details

    • Icon: New Feature New Feature
    • Resolution: Won't Fix
    • Icon: Major - P3 Major - P3
    • None
    • None
    • API
    • None

    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;
      

      Attachments

        Activity

          People

            david.golden@mongodb.com David Golden
            david.golden@mongodb.com David Golden
            Votes:
            0 Vote for this issue
            Watchers:
            3 Start watching this issue

            Dates

              Created:
              Updated:
              Resolved: