CDRIVER-403 Allow count to work with query hints

Support an optional bson_t opt param for count which masses args through
to the count command unchanged.  This allows the user to pass arbitrary
hints.

Adds a new function to the abi

Author: hanumantmk

build/cmake/libmongoc-ssl.def

@@ -43,6 +43,7 @@ mongoc_collection_aggregate
 mongoc_collection_command
 mongoc_collection_command_simple
 mongoc_collection_count
+mongoc_collection_count_with_opts
 mongoc_collection_create_bulk_operation
 mongoc_collection_create_index
 mongoc_collection_delete

build/cmake/libmongoc.def

@@ -43,6 +43,7 @@ mongoc_collection_aggregate
 mongoc_collection_command
 mongoc_collection_command_simple
 mongoc_collection_count
+mongoc_collection_count_with_opts
 mongoc_collection_create_bulk_operation
 mongoc_collection_create_index
 mongoc_collection_delete

doc/mongoc_collection_count_with_opts.page

@@ -0,0 +1,93 @@
+<?xml version="1.0"?>
+
+<page xmlns="http://projectmallard.org/1.0/"
+      type="topic"
+      style="function"
+      xmlns:api="http://projectmallard.org/experimental/api/"
+      xmlns:ui="http://projectmallard.org/experimental/ui/"
+      id="mongoc_collection_count">
+
+
+  <info>
+    <link type="guide" xref="mongoc_collection_t" group="function"/>
+  </info>
+  <title>mongoc_collection_count()</title>
+
+  <section id="synopsis">
+    <title>Synopsis</title>
+    <synopsis><code mime="text/x-csrc"><![CDATA[int64_t
+mongoc_collection_count_with_opts (mongoc_collection_t       *collection,
+                                   mongoc_query_flags_t       flags,
+                                   const bson_t              *query,
+                                   int64_t                    skip,
+                                   int64_t                    limit,
+                                   const bson_t              *opts,
+                                   const mongoc_read_prefs_t *read_prefs,
+                                   bson_error_t              *error);
+]]></code></synopsis>
+  </section>
+
+  <section id="parameters">
+    <title>Parameters</title>
+    <table>
+      <tr><td><p>collection</p></td><td><p>A <link xref="mongoc_collection_t">mongoc_collection_t</link>.</p></td></tr>
+      <tr><td><p>flags</p></td><td><p>A <link xref="mongoc_query_flags_t">mongoc_query_flags_t</link>.</p></td></tr>
+      <tr><td><p>query</p></td><td><p>A bson_t containing the query.</p></td></tr>
+      <tr><td><p>skip</p></td><td><p>A int64_t, zero to ignore.</p></td></tr>
+      <tr><td><p>limit</p></td><td><p>A int64_t, zero to ignore.</p></td></tr>
+      <tr><td><p>opts</p></td><td><p>A bson_t, NULL to ignore.</p></td></tr>
+      <tr><td><p>read_prefs</p></td><td><p>A <link xref="mongoc_read_prefs_t">mongoc_read_prefs_t</link> or NULL.</p></td></tr>
+      <tr><td><p>error</p></td><td><p>An optional location for a <link xref="bson_error_t">bson_error_t</link> or <code>NULL</code>.</p></td></tr>
+    </table>
+  </section>
+
+  <section id="description">
+    <title>Description</title>
+    <p>This function shall execute a count query on the underlying 'collection'. The bson 'query' is not validated, simply passed along as appropriate to the server.  As such, compatibility and errors should be validated in the appropriate server documentation.</p>
+    <p>In addition to the standard functionality available from mongoc_collection_count, this function allows the user to add arbitrary extra keys to the count.  This pass through enables features such as hinting for counts.</p>
+    <p>For more information, see the <link href="http://docs.mongodb.org/manual/reference/operator/query/">query reference</link> at the MongoDB website.</p>
+  </section>
+
+  <section id="errors">
+    <title>Errors</title>
+    <p>Errors are propagated via the <code>error</code> parameter.</p>
+  </section>
+
+  <section id="return">
+    <title>Returns</title>
+    <p>-1 on failure, otherwise the number of documents counted.</p>
+  </section>
+
+  <section id="example">
+    <title>Example</title>
+    <listing>
+      <title>Count Example</title>
+      <code mime="text/x-csrc"><![CDATA[#include <mongoc.h>
+#include <bcon.h>
+#include <stdio.h>
+
+static void
+print_query_count (mongoc_collection_t *collection,
+                   bson_t              *query)
+{
+   bson_error_t error;
+   int64_t count;
+   bson_t opts;
+
+   bson_init(&opts);
+   BSON_APPEND_UTF8(&opts, "hint", "_id_");
+
+   count = mongoc_collection_count (collection, MONGOC_QUERY_NONE, query, 0, 0, &opts, NULL, &error);
+
+   bson_destroy(&opts);
+
+   if (count < 0) {
+      fprintf (stderr, "Count failed: %s\n", error.message);
+   } else {
+      printf ("%"PRId64" documents counted.\n", count);
+   }
+}]]></code>
+    </listing>
+  </section>
+
+</page>

src/libmongoc.symbols

@@ -44,6 +44,7 @@ mongoc_collection_aggregate
 mongoc_collection_command
 mongoc_collection_command_simple
 mongoc_collection_count
+mongoc_collection_count_with_opts
 mongoc_collection_create_bulk_operation
 mongoc_collection_create_index
 mongoc_collection_delete

src/mongoc/mongoc-collection.c

@@ -532,6 +532,28 @@ mongoc_collection_count (mongoc_collection_t       *collection,  /* IN */
                          int64_t               limit,       /* IN */
                          const mongoc_read_prefs_t *read_prefs,  /* IN */
                          bson_error_t              *error)       /* OUT */
+{
+   return mongoc_collection_count_with_opts (
+      collection,
+      flags,
+      query,
+      skip,
+      limit,
+      NULL,
+      read_prefs,
+      error);
+}
+
+
+int64_t
+mongoc_collection_count_with_opts (mongoc_collection_t       *collection,  /* IN */
+                                   mongoc_query_flags_t       flags,       /* IN */
+                                   const bson_t              *query,       /* IN */
+                                   int64_t                    skip,        /* IN */
+                                   int64_t                    limit,       /* IN */
+                                   const bson_t               *opts,       /* IN */
+                                   const mongoc_read_prefs_t *read_prefs,  /* IN */
+                                   bson_error_t              *error)       /* OUT */
 {
    int64_t ret = -1;
    bson_iter_t iter;
@@ -557,6 +579,9 @@ mongoc_collection_count (mongoc_collection_t       *collection,  /* IN */
    if (skip) {
       bson_append_int64(&cmd, "skip", 4, skip);
    }
+   if (opts) {
+       bson_concat(&cmd, opts);
+   }
    if (mongoc_collection_command_simple(collection, &cmd, read_prefs,
                                         &reply, error) &&
        bson_iter_init_find(&iter, &reply, "n")) {

src/mongoc/mongoc-collection.h

@@ -66,6 +66,14 @@ int64_t                       mongoc_collection_count                (mongoc_col
                                                                       int64_t                        limit,
                                                                       const mongoc_read_prefs_t     *read_prefs,
                                                                       bson_error_t                  *error);
+int64_t                       mongoc_collection_count_with_opts      (mongoc_collection_t           *collection,
+                                                                      mongoc_query_flags_t           flags,
+                                                                      const bson_t                  *query,
+                                                                      int64_t                        skip,
+                                                                      int64_t                        limit,
+                                                                      const bson_t                  *opts,
+                                                                      const mongoc_read_prefs_t     *read_prefs,
+                                                                      bson_error_t                  *error);
 bool                          mongoc_collection_drop                 (mongoc_collection_t           *collection,
                                                                       bson_error_t                  *error);
 bool                          mongoc_collection_drop_index           (mongoc_collection_t           *collection,

tests/test-mongoc-collection.c

@@ -537,6 +537,43 @@ test_count (void)
 }
 
 
+static void
+test_count_with_opts (void)
+{
+   mongoc_collection_t *collection;
+   mongoc_client_t *client;
+   bson_error_t error;
+   int64_t count;
+   bson_t b;
+   bson_t opts;
+
+   client = mongoc_client_new (gTestUri);
+   ASSERT (client);
+
+   collection = mongoc_client_get_collection (client, "test", "test");
+   ASSERT (collection);
+
+   bson_init (&opts);
+
+   BSON_APPEND_UTF8 (&opts, "hint", "_id_");
+
+   bson_init (&b);
+   count = mongoc_collection_count_with_opts (collection, MONGOC_QUERY_NONE, &b,
+                                              0, 0, &opts, NULL, &error);
+   bson_destroy (&b);
+   bson_destroy (&opts);
+
+   if (count == -1) {
+      MONGOC_WARNING ("%s\n", error.message);
+   }
+
+   ASSERT (count != -1);
+
+   mongoc_collection_destroy (collection);
+   mongoc_client_destroy (client);
+}
+
+
 static void
 test_drop (void)
 {
@@ -1183,6 +1220,7 @@ test_collection_install (TestSuite *suite)
    TestSuite_Add (suite, "/Collection/update", test_update);
    TestSuite_Add (suite, "/Collection/remove", test_remove);
    TestSuite_Add (suite, "/Collection/count", test_count);
+   TestSuite_Add (suite, "/Collection/count_with_opts", test_count_with_opts);
    TestSuite_Add (suite, "/Collection/drop", test_drop);
    TestSuite_Add (suite, "/Collection/aggregate", test_aggregate);
    TestSuite_Add (suite, "/Collection/validate", test_validate);