Uploaded image for project: 'C Driver'
  1. C Driver
  2. CDRIVER-3054

Remove "superseded" docs from mongoc_collection_(remove|insert|update)

    • Type: Icon: Task Task
    • Resolution: Fixed
    • Priority: Icon: Major - P3 Major - P3
    • 1.29.0
    • Affects Version/s: None
    • Component/s: libmongoc
    • None
    • Fully Compatible
    • Not Needed

      Scope
      Deprecate or update docs of mongoc_collection_(remove|insert|update)

      Background & Motivation
      mongoc_collection_delete is already deprecated for mongoc_collection_delete_(one|many), which matches naming in the CRUD spec.

      mongoc_collection_(remove|insert|update) are documented as "superseded by" their "(one|many)" counterparts (example). Adding BSON_GNUC_DEPRECATED_FOR attribute was decided against in CDRIVER-2304. But I relent on that reasoning. BSON_GNUC_DEPRECATED_FOR generates compiler warnings on usage. Producing compiler warnings may help users identify use of the deprecated APIs.

      Either choose to fully deprecate these functions, or remove the "superseded" notes.

      mongoc_collection_update supports both update and replace documents. This notably differs from the CRUD spec requirement to distinguish the operations:

      bson_t *selector = bson_new ();
      bson_t *replacement = BCON_NEW ("foo", "bar");
      bson_t *update = BCON_NEW ("$set", "{", "foo", "bar", "}");
      
      // `mongoc_collection_update_one` only does update. Errors on replace.
      {
         ok = mongoc_collection_update_one (coll, selector, update, NULL, NULL, &error);
         ASSERT_OR_PRINT (ok, error);
      
         ok = mongoc_collection_update_one (coll, selector, replacement, NULL, NULL, &error);
         ASSERT (!ok);
         ASSERT_ERROR_CONTAINS (error, MONGOC_ERROR_COMMAND, MONGOC_ERROR_COMMAND_INVALID_ARG, "only works with $");
      }
      
      // `mongoc_collection_replace_one` only does replace. Errors on update.
      {
         ok = mongoc_collection_replace_one (coll, selector, update, NULL, NULL, &error);
         ASSERT (!ok);
         ASSERT_ERROR_CONTAINS (error, MONGOC_ERROR_COMMAND, MONGOC_ERROR_COMMAND_INVALID_ARG, "prohibits $");
      
         ok = mongoc_collection_replace_one (coll, selector, replacement, NULL, NULL, &error);
         ASSERT_OR_PRINT (ok, error);
      }
      
      // `mongoc_collection_update` does update or replace depending on the argument.
      {
         ok = mongoc_collection_update (coll, MONGOC_UPDATE_NONE, selector, update, NULL, &error);
         ASSERT_OR_PRINT (ok, error);
      
         // Does a replace!
         ok = mongoc_collection_update (coll, MONGOC_UPDATE_NONE, selector, replacement, NULL, &error);
         ASSERT_OR_PRINT (ok, error);
      }
      

            Assignee:
            kevin.albertson@mongodb.com Kevin Albertson
            Reporter:
            kevin.albertson@mongodb.com Kevin Albertson
            Votes:
            0 Vote for this issue
            Watchers:
            2 Start watching this issue

              Created:
              Updated:
              Resolved: