DOCSP-30510: Find One Usage Example (#68)

Author: norareidy

source/includes/usage-examples/code-snippets/find-one-async.rs

@@ -0,0 +1,33 @@
+use mongodb::{ 
+    bson::doc,
+    Client,
+    Collection
+};
+use futures::TryStreamExt;
+use serde::{ Deserialize, Serialize };
+
+#[derive(Serialize, Deserialize, Debug)]
+struct Restaurant {
+    name: String,
+    cuisine: 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 result = my_coll.find_one(
+        doc! { "name": "Tompkins Square Bagels" },
+        None
+    ).await?;
+
+    println!("{:#?}", result);
+
+    Ok(())
+}
+

source/includes/usage-examples/code-snippets/find-one-sync.rs

@@ -0,0 +1,29 @@
+use mongodb::{
+    bson::{doc, Document},
+    sync::{Client, Collection}
+};
+use serde::{ Deserialize, Serialize };
+
+#[derive(Serialize, Deserialize, Debug)]
+struct Restaurant {
+    name: String,
+    cuisine: 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 result = my_coll.find_one(
+        doc! { "name": "Tompkins Square Bagels" },
+        None
+    )?;
+
+    println!("{:#?}", result);
+
+    Ok(())
+}

source/usage-examples.txt

@@ -12,6 +12,7 @@ Usage Examples
 
 .. toctree::
 
+   /usage-examples/findOne
    /usage-examples/find
    /usage-examples/replace
    /usage-examples/deleteMany
@@ -89,13 +90,13 @@ of the corresponding usage example.
 Available Usage Examples
 ------------------------
 
+- :ref:`Find a Document <rust-find-one-usage>`
 - :ref:`Find Multiple Documents <rust-find-usage>`
 - :ref:`Replace a Document <rust-replace-usage>`
 - :ref:`Delete Multiple Documents <rust-delete-many-usage>`
 - :ref:`Count Documents <rust-count-usage>`
 
 .. TODO: add Usage Example pages as they are created
-    - :ref:`Find a Document <rust-find-one-usage>`
     - :ref:`Insert a Document <rust-insert-one-usage>`
     - :ref:`Insert Multiple Documents <rust-insert-many-usage>`
     - :ref:`Update a Document <rust-update-one-usage>`

source/usage-examples/find.txt

@@ -25,14 +25,15 @@ learn more about using cursors, see the :ref:`rust-cursor-guide` guide.
 Example
 -------
 
-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 in which the value of
-the ``cuisine`` field is ``"French"``.
+This example retrieves documents from the ``restaurants`` collection in the
+``sample_restaurants`` database that match a query filter. 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 in which the value of the ``cuisine`` field is ``"French"``.
+
+Select the **Asynchronous** or **Synchronous** tab to see corresponding code for each runtime:
 
 .. tabs::
 

source/usage-examples/findOne.txt

@@ -0,0 +1,76 @@
+.. _rust-find-one-usage:
+
+===============
+Find a Document
+===============
+
+You can retrieve a single document in a collection by calling the `find_one() 
+<{+api+}/struct.Collection.html#method.find_one>`__ method on a ``Collection`` instance. 
+
+Pass a query filter to the ``find_one()`` method to return one document in the collection
+that matches the filter. If multiple documents match the query filter, this method returns
+the first matching document according to their :term:`natural order` in the database, or
+according to the sort order specified in a ``FindOneOptions`` instance.
+
+The ``find_one()`` method returns a `Result<Option<T>> <{+api+}/error/type.Result.html>`__
+type. 
+
+.. tip::
+
+    To learn more about retrieving documents, see the :ref:`rust-retrieve-guide` guide.
+
+Example
+-------
+
+This example retrieves a document that matches a query filter from the ``restaurants``
+collection in the ``sample_restaurants`` database. The example populates a ``Restaurant``
+struct with the data from the retrieved document.
+
+This example uses a query filter that matches documents in which the value of the
+``name`` field is ``"Tompkins Square Bagels"``.
+
+Select the **Asynchronous** or **Synchronous** tab to see corresponding code for each runtime:
+
+.. tabs::
+
+   .. tab:: Asynchronous
+      :tabid: find-async
+
+      .. io-code-block::
+         :copyable: true
+
+        .. input:: /includes/usage-examples/code-snippets/find-one-async.rs
+            :language: rust
+            :dedent:
+
+        .. output::
+            :language: console
+            :visible: false
+
+            Some(
+                Restaurant {
+                    name: "Tompkins Square Bagels",
+                    cuisine: "American",
+                },
+            )
+
+   .. tab:: Synchronous
+      :tabid: find-sync
+
+      .. io-code-block::
+         :copyable: true
+
+        .. input:: /includes/usage-examples/code-snippets/find-one-sync.rs
+            :language: rust
+            :dedent:
+
+        .. output::
+            :language: console
+            :visible: false
+
+            Some(
+                Restaurant {
+                    name: "Tompkins Square Bagels",
+                    cuisine: "American",
+                },
+            )