SYNOPSIS

          bool
          mongoc_collection_find_and_modify (mongoc_collection_t *collection,
                                             const bson_t *query,
                                             const bson_t *sort,
                                             const bson_t *update,
                                             const bson_t *fields,
                                             bool _remove,
                                             bool upsert,
                                             bool _new,
                                             bson_t *reply,
                                             bson_error_t *error);

PARAMETERS

       • collection: A mongoc_collection_t.

       • query: A bson_t containing the query to locate target document(s).

       • sort: A bson_t containing the sort order for query.

       • update: A bson_t containing an update spec.

       • fields: An optional bson_t containing the fields to return or NULL.

       • _remove: If the matching documents should be removed.

       • upsert: If an upsert should be performed.

       • _new: If the new version of the document should be returned.

       • reply: A maybe-NULL pointer to overwritable storage for a bson_t to contain the results.

       • error: An optional location for a bson_error_t or NULL.

DESCRIPTION

       Update and return an object.

       This  is  a  thin  wrapper  around  the  findAndModify  command.  Either update or _remove
       arguments are required.

       As of MongoDB 3.2, the mongoc_write_concern_t specified on the mongoc_collection_t will be
       used, if any.

       reply is always initialized, and must be freed with bson_destroy().

       On  success, the output reply contains the full server reply to the findAndModify command.
       See the MongoDB Manual page for findAndModify for the expected server reply.

ERRORS

       Errors are propagated via the error parameter.

RETURNS

       If given invalid arguments or a server/network error occurs, returns false and sets error.
       Otherwise,  succeeds  and returns true.  A write concern timeout or write concern error is
       considered a failure.

       SEE ALSO:
          mongoc_collection_find_and_modify_with_opts().

EXAMPLE

       find-and-modify.c

          #include <mongoc/mongoc.h>
          #include <stdio.h>

          int
          main (void)
          {
             mongoc_collection_t *collection;
             mongoc_client_t *client;
             const char *uri_string =
                "mongodb://127.0.0.1:27017/?appname=find-and-modify-example";
             mongoc_uri_t *uri;
             bson_error_t error;
             bson_t *query;
             bson_t *update;
             bson_t reply;
             char *str;

             mongoc_init ();

             uri = mongoc_uri_new_with_error (uri_string, &error);
             if (!uri) {
                fprintf (stderr,
                         "failed to parse URI: %s\n"
                         "error message:       %s\n",
                         uri_string,
                         error.message);
                return EXIT_FAILURE;
             }

             client = mongoc_client_new_from_uri (uri);
             if (!client) {
                return EXIT_FAILURE;
             }

             mongoc_client_set_error_api (client, 2);
             collection = mongoc_client_get_collection (client, "test", "test");

             /*
              * Build our query, {"cmpxchg": 1}
              */
             query = BCON_NEW ("cmpxchg", BCON_INT32 (1));

             /*
              * Build our update. {"$set": {"cmpxchg": 2}}
              */
             update = BCON_NEW ("$set", "{", "cmpxchg", BCON_INT32 (2), "}");

             /*
              * Submit the findAndModify.
              */
             if (!mongoc_collection_find_and_modify (collection,
                                                     query,
                                                     NULL,
                                                     update,
                                                     NULL,
                                                     false,
                                                     false,
                                                     true,
                                                     &reply,
                                                     &error)) {
                fprintf (stderr, "find_and_modify() failure: %s\n", error.message);
                return EXIT_FAILURE;
             }

             /*
              * Print the result as JSON.
              */
             str = bson_as_canonical_extended_json (&reply, NULL);
             printf ("%s\n", str);
             bson_free (str);

             /*
              * Cleanup.
              */
             bson_destroy (query);
             bson_destroy (update);
             bson_destroy (&reply);
             mongoc_collection_destroy (collection);
             mongoc_uri_destroy (uri);
             mongoc_client_destroy (client);

             mongoc_cleanup ();

             return EXIT_SUCCESS;
          }

AUTHOR

       MongoDB, Inc

COPYRIGHT

       2017-present, MongoDB, Inc