DOCSP-30519: count usage ex (#70)

(cherry picked from commit b63847b)

Author: rustagir

source/fundamentals/crud/read-operations/query.txt

@@ -106,7 +106,7 @@ Literal Values
 Literal value query filters allow you to query for data that exactly matches
 a value you provide in the query filter. The following operation uses a
 literal query to search for documents containing a field called ``name``
-that has the value of ``pear``:
+that has the value of ``"pear"``:
 
 .. io-code-block::
    :copyable: true
@@ -356,8 +356,8 @@ Array operators check the values or amount of elements in an array-valued field.
 Example
 ~~~~~~~
 
-The following example matches documents where the ``vendor`` contains
-``C``:
+The following example matches documents where the ``vendor`` array field
+contains ``"C"``:
 
 
 .. io-code-block::

source/includes/usage-examples/code-snippets/count-async.rs

@@ -0,0 +1,27 @@
+use std::env;
+
+use mongodb::{ bson::doc, Client, Collection };
+use serde::{ Deserialize, Serialize };
+
+#[derive(Serialize, Deserialize, Debug)]
+struct Restaurant {
+    name: String,
+}
+
+#[tokio::main]
+async fn main() -> mongodb::error::Result<()> {
+    let uri = "<connection string>";
+
+    let client = Client::with_uri_str(uri).await?;
+    let my_coll: Collection<Restaurant> = client
+        .database("sample_restaurants")
+        .collection("restaurants");
+
+    let ct = my_coll.estimated_document_count(None).await?;
+    println!("Number of documents: {}", ct);
+
+    let ct = my_coll.count_documents(doc! { "name": doc! { "$regex": "Sunset" } }, None).await?;
+    println!("Number of matching documents: {}", ct);
+
+    Ok(())
+}

source/includes/usage-examples/code-snippets/count-sync.rs

@@ -0,0 +1,26 @@
+use std::env;
+
+use mongodb::{ bson::doc, sync::{ Client, Collection } };
+use serde::{ Deserialize, Serialize };
+
+#[derive(Serialize, Deserialize, Debug)]
+struct Restaurant {
+    name: String,
+}
+
+fn main() -> mongodb::error::Result<()> {
+    let uri = "<connection string>";
+
+    let client = Client::with_uri_str(uri)?;
+    let my_coll: Collection<Restaurant> = client
+        .database("sample_restaurants")
+        .collection("restaurants");
+
+    let ct = my_coll.estimated_document_count(None)?;
+    println!("Number of documents: {}", ct);
+
+    let ct = my_coll.count_documents(doc! { "name": doc! { "$regex": "Sunset" } }, None)?;
+    println!("Number of matching documents: {}", ct);
+
+    Ok(())
+}

source/usage-examples.txt

@@ -13,6 +13,7 @@ Usage Examples
 .. toctree::
 
    /usage-examples/find
+   /usage-examples/count
 
 Overview
 --------
@@ -22,11 +23,13 @@ operations. Each usage example includes the following:
 
 - Description of the MongoDB operation
 - Asynchronous and synchronous Rust code examples that you can run in
-  your own environment
+  your environment
 - Output printed by the code example
 
-.. TODO: To learn more about the runtimes offered by the {+driver-short+},
-   see <add link to runtimes page>.
+.. tip:: Asynchronous and Synchronous APIs
+   
+   To learn more about selecting and using different runtime APIs in the
+   {+driver-short+}, see the :ref:`rust-runtimes` guide.
 
 How to Use the Usage Examples
 -----------------------------
@@ -85,6 +88,7 @@ Available Usage Examples
 ------------------------
 
 - :ref:`Find Multiple Documents <rust-find-usage>`
+- :ref:`Count Documents <rust-count-usage>`
 
 .. TODO: add Usage Example pages as they are created
     - :ref:`Find a Document <rust-find-one-usage>`
@@ -95,7 +99,6 @@ Available Usage Examples
     - :ref:`Replace a Document <rust-replace-usage>`
     - :ref:`Delete a Document <rust-delete-one-usage>`
     - :ref:`Delete Multiple Documents <rust-delete-many-usage>`
-    - :ref:`Count Documents <rust-count-usage>`
     - :ref:`Find Distinct Values <rust-distinct-usage>`
 
 

source/usage-examples/count.txt

@@ -0,0 +1,76 @@
+.. _rust-count-usage:
+
+===============
+Count Documents
+===============
+
+You can count the number of documents in a collection by calling one of
+the following methods on a ``Collection`` instance:
+
+- `count_documents() <{+api+}/struct.Collection.html#method.count_documents>`__:
+  counts the number of documents that match a query filter. To learn
+  more about creating query filters, see the :ref:`rust-query-guide`
+  guide.
+
+- `estimated_document_count() <{+api+}/struct.Collection.html#method.estimated_document_count>`__:
+  estimates the total number of documents in a collection by using
+  collection metadata.
+
+Each method returns the count as a ``u64`` instance.
+
+.. note::
+   
+   If you don't pass a filter to the ``count_documents()`` method,
+   MongoDB counts the total number of documents in the collection.
+
+Example
+-------
+
+This example counts documents in the ``restaurants`` collection of the
+``sample_restaurants`` database. The example uses a ``Restaurant``
+struct that has a ``name`` field to model the documents in the
+collection.
+
+The following code first uses the ``estimated_document_count()`` method
+to count the total number of documents in the collection. Then, the
+example uses the ``count_documents()`` method to count the number of
+documents that match a query filter. The filter matches documents in which
+the value of the ``name`` field includes the string ``"Sunset"``.
+
+.. tabs::
+
+   .. tab:: Asynchronous
+      :tabid: find-async
+
+      .. io-code-block::
+         :copyable: true
+
+        .. input:: /includes/usage-examples/code-snippets/count-async.rs
+            :language: rust
+            :dedent:
+
+        .. output::
+            :language: console
+            :visible: false
+
+            // Your values might differ
+            Number of documents: 25216
+            Number of matching documents: 10
+
+   .. tab:: Synchronous
+      :tabid: find-sync
+
+      .. io-code-block::
+         :copyable: true
+
+        .. input:: /includes/usage-examples/code-snippets/count-sync.rs
+            :language: rust
+            :dedent:
+
+        .. output::
+            :language: console
+            :visible: false
+
+            // Your values might differ
+            Number of documents: 25216
+            Number of matching documents: 10

source/usage-examples/find.txt

@@ -4,25 +4,35 @@
 Find Multiple Documents
 =======================
 
-You can query for multiple documents in a collection by calling the ``find()``
-method on a ``Collection`` instance. 
+You can query for multiple documents in a collection by calling the
+`find() <{+api+}/struct.Collection.html#method.find>`__ method on a
+``Collection`` instance.
 
 Pass a query filter to the ``find()`` method to return documents in the collection
 that match the filter. If you do not include a filter, MongoDB returns all the
 documents in the collection.
 
-The ``find()`` method returns a ``Cursor`` type, which you can iterate through
-to retrieve individual documents.
+.. tip::
+
+   To learn more about retrieving documents,
+   see the :ref:`rust-retrieve-guide` guide, and to learn more about
+   creating query filters, see the :ref:`rust-query-guide` guide.
+
+The ``find()`` method returns a `Cursor <{+api+}/struct.Cursor.html>`__
+type, which you can iterate through to retrieve individual documents. To
+learn more about using cursors, see the :ref:`rust-cursor-guide` guide.
 
 Example
 -------
 
-This example finds documents from the ``sample_restaurants.restaurants`` collection
-that match a query filter. The example uses a ``Restaurant`` struct that has ``name``
-and ``cuisine`` fields to model the documents in the collection.
+This example finds documents that match a query filter in the
+``restaurants`` collection of the ``sample_restaurants`` database. The
+example uses a ``Restaurant`` struct that has ``name`` and ``cuisine``
+fields to model the documents in the collection.
 
-The following code passes a query filter as a parameter to the ``find()`` method. The
-filter matches documents where the value of the ``cuisine`` field is ``"French"``.
+The following code passes a query filter as a parameter to the
+``find()`` method. The filter matches documents in which the value of
+the ``cuisine`` field is ``"French"``.
 
 .. tabs::
 
@@ -65,21 +75,3 @@ filter matches documents where the value of the ``cuisine`` field is ``"French"`
             Restaurant { name: "Cafe Un Deux Trois", cuisine: "French" }
             Restaurant { name: "Calliope", cuisine: "French" }
             ...
-
-Additional Information
-----------------------
-
-To learn more about retrieving documents, see the :ref:`rust-retrieve-guide` guide.
-
-To learn more about using cursors, see the :ref:`rust-cursor-guide` guide.
-
-To learn more about using query filters, see the :ref:`rust-query-guide` guide.
-
-API Documentation
-~~~~~~~~~~~~~~~~~
-
-To learn more about the methods and types mentioned on this
-page, see the following API documentation:
-
-- `find() <{+api+}/struct.Collection.html#method.find>`__
-- `Cursor <{+api+}/struct.Cursor.html>`__