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); }
- is related to
-
CDRIVER-2304 Deprecate mongoc_collection_update
- Closed
-
CDRIVER-3052 Documentation examples should not use mongoc_collection_update
- Closed