<page xmlns="http://projectmallard.org/1.0/"
      type="topic"
      id="deleting-document">

  <info>
    <link type="guide" xref="index#getting-started" />
  </info>

  <title>Deleting a Document</title>

  <p>The following guide will step you through the process of connecting to MongoDB and deleting a document.</p>

  <include href="basic-prequisites.xml" xmlns="http://www.w3.org/2001/XInclude" />

  <section id="deleting-basics">
    <title>The Basics</title>

    <p>
      The following code example creates a new <code>mongoc_client_t</code> that we will use to communicate with MongoDB.
      The <link href="http://docs.mongodb.org/manual/reference/connection-string/">Connection String URI</link> component is quite comprehensive.
    </p>

    <p>
      Using our <code>mongoc_client_t</code>, we get a handle to a <code>mongoc_collection_t</code> which represents the remote collection.
      We create a new document, initialized with an <code>_id</code> and a field named <code>hello</code> and insert it into the <code>test.test</code> collection.
      Immediately after, we remove the document matching the <code>_id</code> we inserted.
    </p>

    <p>
      Lastly, we release all of our heap allocated structures.
    </p>

    <listing>
      <title><file>example4.c</file></title>
      <desc>Removing a document from a collection.</desc>
      <synopsis><code mime="text/x-csrc"><![CDATA[#include <bson.h>
#include <mongoc.h>
#include <stdio.h>

int
main (int   argc,
      char *argv[])
{
    mongoc_client_t *client;
    mongoc_collection_t *collection;
    mongoc_cursor_t *cursor;
    bson_error_t error;
    bson_oid_t oid;
    bson_t *doc;

    mongoc_init ();

    client = mongoc_client_new ("mongodb://localhost:27017/");
    collection = mongoc_client_get_collection (client, "test", "test");

    doc = bson_new ();
    bson_oid_init (&oid, NULL);
    BSON_APPEND_OID (doc, "_id", &oid);
    BSON_APPEND_UTF8 (doc, "hello", "world");

    if (!mongoc_collection_insert (collection, MONGOC_INSERT_NONE, doc, NULL, &error)) {
        printf ("Insert failed: %s\n", error.message);
    }

    bson_destroy (doc);

    doc = bson_new ();
    BSON_APPEND_OID (doc, "_id", &oid);

    if (!mongoc_collection_delete (collection, MONGOC_DELETE_SINGLE_REMOVE, doc, NULL, &error)) {
        printf ("Delete failed: %s\n", error.message);
    }

    bson_destroy (doc);
    mongoc_collection_destroy (collection);
    mongoc_client_destroy (client);

    return 0;
}
]]></code></synopsis>
    </listing>

    <p>Let's use <code>GCC</code> and <code>pkg-config</code> to compile <file>example3.c</file>.</p>
    <screen>gcc -o example4 example4.c $(pkg-config --cflags --libs libmongoc-1.0)</screen>

    <note style="warning">
      <p>
        When using the MongoDB C Driver, you must call <link xref="mongoc_init">mongoc_init()</link> at the beginning of your application.
        This allows the driver to initialize it's required subsystems.
        Failure to do so will result in a runtime crash.
      </p>
    </note>

    <p>Now let's run it!</p>

    <screen>./example4</screen>

  </section>

</page>
