Merge remote-tracking branch 'upstream/master' into v2.7

Author: rustagir

source/fundamentals/database-collection.txt

@@ -251,6 +251,8 @@ a database referenced by the ``db`` variable by using the
 
       ["my_coll", "coll_xyz", ...]
 
+.. _rust-drop-collection:
+
 Drop a Collection
 -----------------
 

source/includes/usage-examples/code-snippets/delete-many-async.rs

@@ -0,0 +1,40 @@
+use mongodb::{ 
+    bson::doc,
+    Client,
+    Collection 
+};
+use serde::{ Deserialize, Serialize };
+
+#[derive(Serialize, Deserialize, Debug)]
+struct Restaurant {
+    address: Address,
+    borough: String,
+}
+
+#[derive(Serialize, Deserialize, Debug)]
+struct Address {
+    street: 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! { "$and": [
+           doc! { "borough": "Manhattan" },
+           doc! { "address.street": "Broadway" }
+       ]
+    };
+
+    let result = my_coll.delete_many(filter, None).await?;
+
+    println!("Deleted documents: {}", result.deleted_count);
+
+    Ok(())
+}

source/includes/usage-examples/code-snippets/delete-many-sync.rs

@@ -0,0 +1,38 @@
+use mongodb::{
+    bson::doc,
+    sync::{Client, Collection}
+};
+use serde::{ Deserialize, Serialize };
+
+#[derive(Serialize, Deserialize, Debug)]
+struct Restaurant {
+    address: Address,
+    borough: String,
+}
+
+#[derive(Serialize, Deserialize, Debug)]
+struct Address {
+    street: 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! { "$and": [
+           doc! { "borough": "Manhattan" },
+           doc! { "address.street": "Broadway" }
+       ]
+    };
+
+    let result = my_coll.delete_many(filter, None)?;
+
+    println!("Deleted documents: {}", result.deleted_count);
+
+    Ok(())
+}

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,8 @@ Usage Examples
 .. toctree::
 
    /usage-examples/find
+   /usage-examples/replace
+   /usage-examples/deleteMany
    /usage-examples/count
 
 Overview
@@ -88,6 +90,8 @@ 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>`
 
 .. TODO: add Usage Example pages as they are created
@@ -96,9 +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:`Delete Multiple Documents <rust-delete-many-usage>`
     - :ref:`Find Distinct Values <rust-distinct-usage>`
-
-

source/usage-examples/deleteMany.txt

@@ -0,0 +1,76 @@
+.. _rust-delete-many-usage:
+
+=========================
+Delete Multiple Documents
+=========================
+
+You can delete multiple documents from a collection in a single operation
+by calling the `delete_many() <{+api+}/struct.Collection.html#method.delete_many>`__
+method on a ``Collection`` instance.
+
+Pass a query filter to the ``delete_many()`` method to delete documents in the
+collection that match the filter. If you do not include a filter, MongoDB deletes
+all the documents in the collection. 
+
+The ``delete_many()`` method returns a `DeleteResult <{+api+}/results/struct.DeleteResult.html>`__
+type. This type contains information about the delete operation, such as the total
+number of documents deleted.
+
+To learn more about delete operations, see the :ref:`rust-delete-guide` guide.
+
+.. tip::
+
+    To delete all documents in a collection, consider calling the ``drop()``
+    method on a ``Collection`` instance. To learn more about the ``drop()`` 
+    method, see the :ref:`rust-drop-collection` section of the Databases and
+    Collections guide.
+
+Example
+-------
+
+This example deletes all the documents from the ``restaurants`` collection that
+match a query filter. The example uses a ``Restaurant`` struct that has ``address``
+and ``borough`` fields to model the documents in the collection. 
+
+This example passes a query filter as a parameter to the ``delete_many()`` method.
+The filter matches documents where the value of the ``borough`` field is ``"Manhattan"``
+and the value of the ``address.street`` field is ``"Broadway"``.
+
+Select the **Asynchronous** or **Synchronous** tab to see corresponding code for each runtime:
+
+.. tabs::
+
+   .. tab:: Asynchronous
+      :tabid: delete-many-async
+
+      .. io-code-block::
+         :copyable: true
+
+        .. input:: /includes/usage-examples/code-snippets/delete-many-async.rs
+            :language: rust
+            :dedent:
+
+        .. output::
+            :language: console
+            :visible: false
+
+            // Your values might differ
+            Deleted documents: 615
+
+   .. tab:: Synchronous
+      :tabid: find-sync
+
+      .. io-code-block::
+         :copyable: true
+
+        .. input:: /includes/usage-examples/code-snippets/delete-many-sync.rs
+            :language: rust
+            :dedent:
+
+        .. output::
+            :language: console
+            :visible: false
+
+            // Your values might differ
+            Deleted documents: 615
+

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