DOCSP-30516: replace usage example (#73)

Author: rustagir

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

@@ -0,0 +1,36 @@
+use std::env;
+use mongodb::{ bson::doc, Client, Collection };
+use serde::{ Deserialize, Serialize };
+
+#[derive(Serialize, Deserialize, Debug)]
+struct Restaurant {
+    borough: String,
+    cuisine: String,
+    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 filter = doc! { "name": "Landmark Coffee Shop" };
+    let replacement = Restaurant {
+        borough: "Brooklyn".to_string(),
+        cuisine: "Café/Coffee/Tea".to_string(),
+        name: "Harvest Moon Café".to_string(),
+    };
+
+    let res = my_coll.replace_one(filter, replacement, None).await?;
+    println!(
+        "Matched documents: {}\nReplaced documents: {}",
+        res.matched_count,
+        res.modified_count
+    );
+
+    Ok(())
+}

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

@@ -0,0 +1,35 @@
+use std::env;
+use mongodb::{ bson::doc, sync::{ Client, Collection } };
+use serde::{ Deserialize, Serialize };
+
+#[derive(Serialize, Deserialize, Debug)]
+struct Restaurant {
+    borough: String,
+    cuisine: String,
+    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 filter = doc! { "name": "Landmark Coffee Shop" };
+    let replacement = Restaurant {
+        borough: "Brooklyn".to_string(),
+        cuisine: "Café/Coffee/Tea".to_string(),
+        name: "Harvest Moon Café".to_string(),
+    };
+
+    let res = my_coll.replace_one(filter, replacement, None)?;
+    println!(
+        "Matched documents: {}\nReplaced documents: {}",
+        res.matched_count,
+        res.modified_count
+    );
+
+    Ok(())
+}

source/usage-examples.txt

@@ -13,6 +13,7 @@ Usage Examples
 .. toctree::
 
    /usage-examples/find
+   /usage-examples/replace
    /usage-examples/deleteMany
    /usage-examples/count
 
@@ -89,6 +90,7 @@ Available Usage Examples
 ------------------------
 
 - :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>`
 
@@ -98,8 +100,5 @@ Available Usage Examples
     - :ref:`Insert Multiple Documents <rust-insert-many-usage>`
     - :ref:`Update a Document <rust-update-one-usage>`
     - :ref:`Update Multiple Documents <rust-update-many-usage>`
-    - :ref:`Replace a Document <rust-replace-usage>`
     - :ref:`Delete a Document <rust-delete-one-usage>`
-    - :ref:`Find Distinct Values <rust-distinct-usage>`
-
-
+    - :ref:`Find Distinct Values <rust-distinct-usage>`

source/usage-examples/replace.txt

@@ -0,0 +1,71 @@
+.. _rust-replace-usage:
+
+==================
+Replace a Document
+==================
+
+You can replace a document in a collection by calling the `replace_one()
+<{+api+}/struct.Collection.html#method.replace_one>`__ method on a
+``Collection`` instance.
+
+Pass the following parameters to the ``replace_one()`` method to update
+a document:
+
+- Query filter, which specifies the criteria to match
+- Replacement document, which contains the fields and values that will
+  replace an existing document
+
+The ``replace_one()`` method returns an `UpdateResult
+<{+api+}/results/struct.UpdateResult.html>`__ type which contains
+information about the result of the replace operation, such as the
+number of modified documents.
+
+To learn more about the ``replace_one()`` method, see the
+:ref:`rust-replace-document` section of the Modify Documents guide.
+
+Example
+-------
+
+This example replaces a document in the ``restaurants`` collection of
+the ``sample_restaurants`` database. The example uses a ``Restaurant``
+struct that has ``name``, ``borough``, and ``cuisine`` fields to model
+documents in the collection.
+
+The following code replaces a document in which the value of the
+``name`` field is ``"Landmark Coffee Shop"`` with a new document:
+
+.. tabs::
+
+   .. tab:: Asynchronous
+      :tabid: find-async
+
+      .. io-code-block::
+         :copyable: true
+
+        .. input:: /includes/usage-examples/code-snippets/replace-async.rs
+            :language: rust
+            :dedent:
+
+        .. output::
+            :language: console
+            :visible: false
+
+            Matched documents: 1
+            Replaced documents: 1
+
+   .. tab:: Synchronous
+      :tabid: find-sync
+
+      .. io-code-block::
+         :copyable: true
+
+        .. input:: /includes/usage-examples/code-snippets/replace-sync.rs
+            :language: rust
+            :dedent:
+
+        .. output::
+            :language: console
+            :visible: false
+
+            Matched documents: 1
+            Replaced documents: 1