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

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.

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;
    }