NAME

       mongoc_collection_find_and_modify - mongoc_collection_find_and_modify()

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:  Optional  pointer  to  an uninitialized bson_t that will be initialized with the
         result.

       • 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.

       See also: mongoc_collection_find_and_modify_with_opts.

       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().

ERRORS

       Errors are propagated via the error parameter.

RETURNS

       Returns either the document before or after modification based on the _new parameter.

       A write concern timeout or write concern error is considered a failure.

EXAMPLE

       find-and-modify.c.INDENT 0.0

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

          int
          main (int argc, char *argv[])
          {
             mongoc_collection_t *collection;
             mongoc_client_t *client;
             bson_error_t error;
             bson_t *query;
             bson_t *update;
             bson_t reply;
             char *str;

             mongoc_init ();

             client = mongoc_client_new (
                "mongodb://127.0.0.1:27017/?appname=find-and-modify-example");
             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 1;
             }

             /*
              * 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_client_destroy (client);

             mongoc_cleanup ();

             return 0;
          }

AUTHOR

       MongoDB, Inc

COPYRIGHT

       2018, MongoDB, Inc