From 5dac54b8be7d257510696d40fe2a18874f51b210 Mon Sep 17 00:00:00 2001 From: norareidy Date: Thu, 21 Dec 2023 15:47:16 -0500 Subject: [PATCH 01/10] adding content --- source/faq.txt | 160 +++++++++++++++++++++++++++++++++++++++++++++++ source/index.txt | 11 ++-- 2 files changed, 165 insertions(+), 6 deletions(-) create mode 100644 source/faq.txt diff --git a/source/faq.txt b/source/faq.txt new file mode 100644 index 00000000..5d464c01 --- /dev/null +++ b/source/faq.txt @@ -0,0 +1,160 @@ +.. _rust-faq: + +=== +FAQ +=== + +.. facet:: + :name: genre + :values: reference + +.. meta:: + :keywords: code example, connection error, question, help + +.. contents:: On this page + :local: + :backlinks: none + :depth: 1 + :class: singlecol + +On this page, you can find frequently asked questions and their corresponding answers. + +.. tip:: + + If you can't find an answer to your problem on this page, see the + :ref:`rust-issues-and-help` page for next steps and more resources. + +Why Am I Getting Errors While Connecting to MongoDB? +---------------------------------------------------- + +If you have trouble connecting to a MongoDB deployment, see the +:ref:`rust-connection-troubleshooting` guide for possible solutions. + +.. _rust-faq-connection-pool: + +How Does Connection Pooling Work in the {+driver-short+}? +--------------------------------------------------------- + +Each server in your MongoDB topology has a corresponding ``Client`` instance, +which manages the server's connection pool. Connection pools open sockets on +demand to support concurrent operations in your multi-threaded application. + +You can configure the following connection pool features: + +- Maximum and minimum size, set by the ``max_pool_size`` and ``min_pool_size`` options +- Maximum number of connections that the pool creates in parallel, set by the ``max_connecting`` + option +- Maximum idle time, set by the ``max_idle_time`` option + +For more information about connection pooling, see the :ref:`rust-performance-pool` +section of the Performance Considerations guide. + +How Do I Fix the "Trait bounds were not satisfied" Error? +--------------------------------------------------------- + +Trait bounds provide a way for methods to restrict which types they +accept as parameters and what functionality those types must implement. +For example, if you define a method that accepts a generic type parameter +and prints its value, that parameter must implement the ``Display`` trait +for printing purposes. The following example defines the ``printer`` method +and specifies that the method's parameter must implement ``Display``: + +.. code-block:: rust + :copyable: true + + fn printer(t: T) { + println!("{}", t); + } + +When calling a method on a data type, you may encounter an error stating that +the method exists for your specified data type but its trait bounds are not +satisfied. For example, the driver might raise the following error message when +you call the ``try_next()`` method on a ``Cursor`` instance: + +.. code-block:: rust + :copyable: false + + error[E0599]: the method `try_next` exists for struct `mongodb::Cursor`, + but its trait bounds were not satisfied + +The ``Cursor`` type implements the ``Stream`` trait and has access to the +``TryStreamExt`` methods, including ``try_next()``. However, ``Cursor`` only +implements ``Stream`` if the trait bounds for ``T`` are satisfied. Namely, ``T`` +must implement the ``DeserializeOwned`` trait, as specified in the `Cursor +<{+api+}/struct.Cursor.html/>`__ API documentation. + +To resolve the preceding error, identify the data type over which the cursor +iterates and ensure that this data type implements the ``DeserializeOwned`` trait. +You can use a ``where`` clause to apply the required trait bounds. + +For more information about trait bounds, see the following resources: + +- :community-forum:`Cursor trait bounds ` + question in the Community Forums +- `Bounds `__ in the + Rust language documentation +- `Where clauses `__ + in the Rust language documentation + +How Do I Convert Between BSON and Rust Types? +--------------------------------------------- + +The {+driver-short+} and the BSON library use the Serde framework to perform +conversions between custom Rust types, like structs and enums, and BSON. You can +install the ``serde`` crate to access the functionality of the Serde framework. +For instructions on installing this crate, see `serde `__ +at the ``crates.io`` crate registry. + +After installing the ``serde`` crate, you can model the documents in a collection +by using a custom type instead of a BSON document. Add the following ``derive`` +statement before your custom struct definition to allow for serialization, or conversion +to BSON, and deserialization, or conversion to the struct type: + +.. code-block:: rust + :copyable: true + + #[derive(Serialize, Deserialize)] + +You can then instantiate a ``Collection`` instance with your custom struct type as its +generic type parameter. + +For more information about converting between BSON and Rust types, see the +:ref:`rust-serialization` guide and the :website:`Structuring Data with Serde in Rust +` MongoDB Developer Center article. + +How Do I Process Values Wrapped in ``Result`` and ``Option`` Enums? +------------------------------------------------------------------- + +The Rust language provides the ``Result`` and ``Option`` enums as safeguards for +your application code. Many methods provided by the {+driver-short+} return values +wrapped in one of these two types. The ``Result`` enum has an ``Ok(T)`` and an ``Err(E)`` +variant, and it wraps the return values of methods that can output either a valid or +an error result. The ``Option`` enum has a ``None`` and a ``Some(T)`` variant, and it +wraps the return values of methods that can output either no value or some value. + +For example, when you use the ``insert_one()`` method to insert a document into a +collection, the insert operation might not succeed. For this reason, the method returns +a ``Result`` type. You can use the ``?`` operator to instruct the driver +to either unwrap the ``InsertOneResult`` if it's valid or return an error if the operation +does not succeed. The following code demonstrates the syntax for using the ``?`` operator +while handling an insert operation result: + +.. code-block:: rust + :copyable: true + + let insert_one_result = my_coll.insert_one(doc, None).await?; + +If the preceding insert operation runs successfully, the ``insert_one_result`` variable +has a value of type ``InsertOneResult``. If the operation is unsuccessful, the code +returns an error. + +Alternatively, you can create custom logic for handling the ``InsertOneResult`` value +depending on whether ``insert_one()`` returns the value wrapped in the ``Ok`` or the ``Err`` +variant. + +For more information about the ``Result`` and ``Option`` enums, see the following +resources in the Rust language documentation: + +- `Result `__ +- `Option `__ +- `? Operator `__ \ No newline at end of file diff --git a/source/index.txt b/source/index.txt index 2072b38a..7086b344 100644 --- a/source/index.txt +++ b/source/index.txt @@ -12,14 +12,13 @@ /usage-examples /fundamentals API Documentation <{+api+}/> + /faq /connection-troubleshooting /op-error-handling /issues-and-help /compatibility View the Source -.. - /faq Introduction ------------ @@ -64,11 +63,11 @@ API For detailed information about types and methods in the {+driver-long+}, see the `API documentation <{+api+}/>`__. -.. FAQ -.. --- +FAQ +--- -.. For answers to commonly asked questions about the {+driver-long+}, see -.. the :ref:`rust-faq` section. +For answers to commonly asked questions about the {+driver-long+}, see +the :ref:`rust-faq` section. Connection Troubleshooting -------------------------- From 390d416e0850653fb4e15e2283c6f3792fdd19d2 Mon Sep 17 00:00:00 2001 From: norareidy Date: Thu, 21 Dec 2023 15:52:45 -0500 Subject: [PATCH 02/10] edits + build --- source/faq.txt | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/source/faq.txt b/source/faq.txt index 5d464c01..878aade0 100644 --- a/source/faq.txt +++ b/source/faq.txt @@ -32,8 +32,8 @@ If you have trouble connecting to a MongoDB deployment, see the .. _rust-faq-connection-pool: -How Does Connection Pooling Work in the {+driver-short+}? ---------------------------------------------------------- +How Does Connection Pooling Work in the Rust Driver? +---------------------------------------------------- Each server in your MongoDB topology has a corresponding ``Client`` instance, which manages the server's connection pool. Connection pools open sockets on @@ -52,12 +52,12 @@ section of the Performance Considerations guide. How Do I Fix the "Trait bounds were not satisfied" Error? --------------------------------------------------------- -Trait bounds provide a way for methods to restrict which types they -accept as parameters and what functionality those types must implement. -For example, if you define a method that accepts a generic type parameter -and prints its value, that parameter must implement the ``Display`` trait -for printing purposes. The following example defines the ``printer`` method -and specifies that the method's parameter must implement ``Display``: +Trait bounds allow methods to restrict which types they accept as parameters +and what functionality those types must implement. For example, if you define +a method that accepts a generic type parameter and prints its value, that parameter +must implement the ``Display`` trait for printing purposes. The following example +defines the ``printer`` method and specifies that the method's parameter must +implement ``Display``: .. code-block:: rust :copyable: true @@ -66,7 +66,7 @@ and specifies that the method's parameter must implement ``Display``: println!("{}", t); } -When calling a method on a data type, you may encounter an error stating that +When calling a method on a data type, you might encounter an error stating that the method exists for your specified data type but its trait bounds are not satisfied. For example, the driver might raise the following error message when you call the ``try_next()`` method on a ``Cursor`` instance: From 00961bb9aaf8df639b4ad4d32f970c0c9af3783b Mon Sep 17 00:00:00 2001 From: norareidy Date: Thu, 21 Dec 2023 16:01:56 -0500 Subject: [PATCH 03/10] fixes --- source/faq.txt | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/source/faq.txt b/source/faq.txt index 878aade0..e8c99910 100644 --- a/source/faq.txt +++ b/source/faq.txt @@ -71,7 +71,7 @@ the method exists for your specified data type but its trait bounds are not satisfied. For example, the driver might raise the following error message when you call the ``try_next()`` method on a ``Cursor`` instance: -.. code-block:: rust +.. code-block:: none :copyable: false error[E0599]: the method `try_next` exists for struct `mongodb::Cursor`, @@ -89,8 +89,8 @@ You can use a ``where`` clause to apply the required trait bounds. For more information about trait bounds, see the following resources: -- :community-forum:`Cursor trait bounds ` - question in the Community Forums +- :community-forum:`Cursor trait bounds question ` + in the Community Forums - `Bounds `__ in the Rust language documentation - `Where clauses `__ From 661215937779988f4aaba64f204ec47c843bb340 Mon Sep 17 00:00:00 2001 From: norareidy Date: Thu, 21 Dec 2023 16:02:56 -0500 Subject: [PATCH 04/10] vale --- source/faq.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/faq.txt b/source/faq.txt index e8c99910..d05e8395 100644 --- a/source/faq.txt +++ b/source/faq.txt @@ -54,7 +54,7 @@ How Do I Fix the "Trait bounds were not satisfied" Error? Trait bounds allow methods to restrict which types they accept as parameters and what functionality those types must implement. For example, if you define -a method that accepts a generic type parameter and prints its value, that parameter +a method that accepts a generic type parameter and prints its value, the parameter must implement the ``Display`` trait for printing purposes. The following example defines the ``printer`` method and specifies that the method's parameter must implement ``Display``: From 0d5dcc97ab06055ded653532708465e2c943fc98 Mon Sep 17 00:00:00 2001 From: norareidy Date: Wed, 3 Jan 2024 15:57:12 -0500 Subject: [PATCH 05/10] CC feedback --- source/faq.txt | 211 ++++++++++++++++++++++++++++++++++--------------- 1 file changed, 147 insertions(+), 64 deletions(-) diff --git a/source/faq.txt b/source/faq.txt index d05e8395..20d97f78 100644 --- a/source/faq.txt +++ b/source/faq.txt @@ -21,11 +21,11 @@ On this page, you can find frequently asked questions and their corresponding an .. tip:: - If you can't find an answer to your problem on this page, see the - :ref:`rust-issues-and-help` page for next steps and more resources. + If you can't find an answer to your question on this page, see the + :ref:`rust-issues-and-help` page for information on how to report issues. -Why Am I Getting Errors While Connecting to MongoDB? ----------------------------------------------------- +Why do I Get Errors While Connecting to MongoDB? +------------------------------------------------ If you have trouble connecting to a MongoDB deployment, see the :ref:`rust-connection-troubleshooting` guide for possible solutions. @@ -35,9 +35,10 @@ If you have trouble connecting to a MongoDB deployment, see the How Does Connection Pooling Work in the Rust Driver? ---------------------------------------------------- -Each server in your MongoDB topology has a corresponding ``Client`` instance, -which manages the server's connection pool. Connection pools open sockets on -demand to support concurrent operations in your multi-threaded application. +Each server in your MongoDB cluster maintains a connection pool. You can access or +manage the behavior of the connection pool by using an instance of a `Client +<{+api+}/struct.Client.html>`__. Connection pools open sockets on demand to support +concurrent operations in your multi-threaded application. You can configure the following connection pool features: @@ -49,15 +50,53 @@ You can configure the following connection pool features: For more information about connection pooling, see the :ref:`rust-performance-pool` section of the Performance Considerations guide. -How Do I Fix the "Trait bounds were not satisfied" Error? ---------------------------------------------------------- +How Do I Convert Between BSON and Rust Types? +--------------------------------------------- + +The {+driver-short+} and the BSON library use the Serde framework to perform +conversions between custom Rust types and BSON. You can install the ``serde`` +crate to access the functionality of the Serde framework. For instructions +on installing this crate, see `serde `__ in the +crates registry. + +After you add the crate to your application, you can model the documents in a collection +by using a custom type instead of a BSON document. The following example includes a ``derive`` +statement before the ``Vegetable`` struct definition, which instructs the driver to +perform the following actions when needed: + +- Serialize the struct, which converts the struct to BSON +- Deserialize BSON, which converts BSON data to your struct + +.. code-block:: rust + :copyable: true + + #[derive(Serialize, Deserialize)] + struct Vegetable { + // Add struct fields here + } + +You can then create a ``Collection`` instance with your custom struct type as its +generic type parameter. The following example instantiates the ``my_coll`` collection +parameterized with the ``Vegetable`` type: + +.. code-block:: rust + :copyable: true + + let my_coll: Collection = client.database("db").collection("actors"); + +For more information about converting between BSON and Rust types, see the +:ref:`rust-serialization` guide and the :website:`Structuring Data with Serde in Rust +` MongoDB Developer Center article. + +How Do I Fix Unsatisfied Trait Bounds Errors? +--------------------------------------------- Trait bounds allow methods to restrict which types they accept as parameters and what functionality those types must implement. For example, if you define a method that accepts a generic type parameter and prints its value, the parameter must implement the ``Display`` trait for printing purposes. The following example -defines the ``printer`` method and specifies that the method's parameter must -implement ``Display``: +defines the ``printer()`` method and specifies that its parameter must implement +``Display``: .. code-block:: rust :copyable: true @@ -67,9 +106,9 @@ implement ``Display``: } When calling a method on a data type, you might encounter an error stating that -the method exists for your specified data type but its trait bounds are not -satisfied. For example, the driver might raise the following error message when -you call the ``try_next()`` method on a ``Cursor`` instance: +the method's trait bounds are not satisfied. For example, the driver might raise +the following error message when you call the ``try_next()`` method on a ``Cursor`` +instance: .. code-block:: none :copyable: false @@ -77,15 +116,50 @@ you call the ``try_next()`` method on a ``Cursor`` instance: error[E0599]: the method `try_next` exists for struct `mongodb::Cursor`, but its trait bounds were not satisfied -The ``Cursor`` type implements the ``Stream`` trait and has access to the -``TryStreamExt`` methods, including ``try_next()``. However, ``Cursor`` only -implements ``Stream`` if the trait bounds for ``T`` are satisfied. Namely, ``T`` +The ``Cursor`` type only implements the ``Stream`` trait, which is required to access +the ``try_next()`` method, if the trait bounds for ``T`` are satisfied. Namely, ``T`` must implement the ``DeserializeOwned`` trait, as specified in the `Cursor -<{+api+}/struct.Cursor.html/>`__ API documentation. +<{+api+}/struct.Cursor.html>`__ API documentation. The following example replicates the +preceding error message by defining a custom ``Actor`` struct to model documents in the +``actors`` collection. However, this struct does not implement the ``DeserializeOwned`` trait, +and using the ``try_next()`` method to iterate over ``Actor`` instances causes an error: -To resolve the preceding error, identify the data type over which the cursor +.. code-block:: rust + :copyable: true + + struct Actor { + name: String, + } + + // Add setup code here + + let my_coll: Collection = client.database("db").collection("actors"); + let mut cursor = my_coll.find(None, None).await?; + while let Some(result) = cursor.try_next().await? { + println!("{:?}", result); + }; + +To resolve the trait bounds error, identify the data type over which the cursor iterates and ensure that this data type implements the ``DeserializeOwned`` trait. -You can use a ``where`` clause to apply the required trait bounds. +You can use a ``derive`` statement to apply the required trait bound. + +.. note:: Deserialize and DeserializeOwned Traits + + The ``serde`` crate provides derive macros to generate the implementation of + certain traits, including the ``Deserialize`` trait. However, this crate does not + offer a derive macro for the ``DeserializeOwned`` trait. Data types that implement + ``Deserialize`` without lifetime restrictions automatically implement ``DeserializeOwned``, + so you can implement ``Deserialize`` to fulfill the ``DeserializeOwned`` trait bound. + +The following example adjusts the ``Actor`` struct definition to implement ``Deserialize``: + +.. code-block:: rust + :copyable: true + + #[derive(Deserialize)] + struct Actor { + name: String, + } For more information about trait bounds, see the following resources: @@ -93,68 +167,77 @@ For more information about trait bounds, see the following resources: in the Community Forums - `Bounds `__ in the Rust language documentation -- `Where clauses `__ +- `Derive `__ in the Rust language documentation -How Do I Convert Between BSON and Rust Types? ---------------------------------------------- +How Do I Process a Value Wrapped in a Result or Option Enum? +------------------------------------------------------------ -The {+driver-short+} and the BSON library use the Serde framework to perform -conversions between custom Rust types, like structs and enums, and BSON. You can -install the ``serde`` crate to access the functionality of the Serde framework. -For instructions on installing this crate, see `serde `__ -at the ``crates.io`` crate registry. +Rust provides the ``Result`` and ``Option`` enums as safeguards for your application +code. Many methods offered by the {+driver-short+} return values wrapped in one of these +two types. -After installing the ``serde`` crate, you can model the documents in a collection -by using a custom type instead of a BSON document. Add the following ``derive`` -statement before your custom struct definition to allow for serialization, or conversion -to BSON, and deserialization, or conversion to the struct type: +The ``Result`` enum can return the following variants: -.. code-block:: rust - :copyable: true +- ``Ok(T)``, which wraps the value of the result of the operation +- ``Err(E)``, which wraps an error value if the operation is unsuccessful + +The ``Option`` enum can return the following variants: - #[derive(Serialize, Deserialize)] +- ``None``, which represents an empty value returned by an operation +- ``Some(T)``, which wraps a nonempty return value -You can then instantiate a ``Collection`` instance with your custom struct type as its -generic type parameter. +For example, the ``insert_one()`` method returns a ``Result`` type to wrap either a successful +response or an error. -For more information about converting between BSON and Rust types, see the -:ref:`rust-serialization` guide and the :website:`Structuring Data with Serde in Rust -` MongoDB Developer Center article. +To access the result of ``insert_one()``, you can use the ``?`` operator to unwrap its +return value. If the operation is successful, the ``?`` operator unwraps the ``InsertOneResult`` +value and assigns it to the ``insert_one_result`` variable. If the operation is unsuccessful, +the ``?`` operator unwraps and returns the error value. The following code demonstrates the +syntax for using the ``?`` operator while handling an insert operation result: -How Do I Process Values Wrapped in ``Result`` and ``Option`` Enums? -------------------------------------------------------------------- +.. code-block:: rust + :copyable: true -The Rust language provides the ``Result`` and ``Option`` enums as safeguards for -your application code. Many methods provided by the {+driver-short+} return values -wrapped in one of these two types. The ``Result`` enum has an ``Ok(T)`` and an ``Err(E)`` -variant, and it wraps the return values of methods that can output either a valid or -an error result. The ``Option`` enum has a ``None`` and a ``Some(T)`` variant, and it -wraps the return values of methods that can output either no value or some value. + let insert_one_result = my_coll.insert_one(doc, None).await?; -For example, when you use the ``insert_one()`` method to insert a document into a -collection, the insert operation might not succeed. For this reason, the method returns -a ``Result`` type. You can use the ``?`` operator to instruct the driver -to either unwrap the ``InsertOneResult`` if it's valid or return an error if the operation -does not succeed. The following code demonstrates the syntax for using the ``?`` operator -while handling an insert operation result: +Alternatively, you can create custom logic for handling the ``InsertOneResult`` value +depending on whether ``insert_one()`` returns the value wrapped in the ``Ok`` or the ``Err`` +variant. The following code uses the ``match`` keyword to process the ``insert_one()`` +result: .. code-block:: rust :copyable: true - let insert_one_result = my_coll.insert_one(doc, None).await?; + let insert_one_result = my_coll.insert_one(doc, None).await; -If the preceding insert operation runs successfully, the ``insert_one_result`` variable -has a value of type ``InsertOneResult``. If the operation is unsuccessful, the code -returns an error. + match insert_one_result { + Ok(val) => { + println!("Document inserted with ID: {}", val.inserted_id); + }, + Err(err) => { + println!("Operation not successful"); + } + } -Alternatively, you can create custom logic for handling the ``InsertOneResult`` value -depending on whether ``insert_one()`` returns the value wrapped in the ``Ok`` or the ``Err`` -variant. +Some {+driver-short+} methods return an ``Option`` type, such as the ``read_concern()`` +method. ``Option`` wraps either an empty value, if no read concern exists, or a ``ReadConcern`` +value. + +To access the result of ``read_concern()``, you can use the ``if let`` syntax. The following code +unwraps and prints the nonempty ``read_concern()`` return value, if it exists: + +.. code-block:: rust + :copyable: true + + if let Some(rc) = my_coll.read_concern() { + println!("Read concern: {:?}", rc); + } For more information about the ``Result`` and ``Option`` enums, see the following resources in the Rust language documentation: -- `Result `__ -- `Option `__ -- `? Operator `__ \ No newline at end of file +- `Result `__ +- `Option `__ +- `? Operator `__ +- `If Let `__ \ No newline at end of file From e2409c79aa132adc42c10dcad40b97f136389cce Mon Sep 17 00:00:00 2001 From: norareidy Date: Wed, 3 Jan 2024 16:07:50 -0500 Subject: [PATCH 06/10] small edits --- source/faq.txt | 13 ++++++++----- 1 file changed, 8 insertions(+), 5 deletions(-) diff --git a/source/faq.txt b/source/faq.txt index 20d97f78..698bb5bc 100644 --- a/source/faq.txt +++ b/source/faq.txt @@ -221,11 +221,14 @@ result: } Some {+driver-short+} methods return an ``Option`` type, such as the ``read_concern()`` -method. ``Option`` wraps either an empty value, if no read concern exists, or a ``ReadConcern`` -value. - -To access the result of ``read_concern()``, you can use the ``if let`` syntax. The following code -unwraps and prints the nonempty ``read_concern()`` return value, if it exists: +method. This method returns an ``Option`` that wraps either an empty value, if no read +concern exists, or a ``ReadConcern`` value. + +To access the result of ``read_concern()``, you can use the same ``match`` syntax as shown +in the preceding example. When using ``match``, replace the ``Ok(T)`` and ``Err(E)`` enum variants +with ``None`` and ``Some(T)``. Additionally, you can use the ``if let`` syntax to process only +the ``Some(T)`` variant. The following code unwraps and prints the nonempty ``read_concern()`` +return value, if it exists: .. code-block:: rust :copyable: true From 9767f88fd363b03b2bf0c75748386ac401d3ab8d Mon Sep 17 00:00:00 2001 From: norareidy Date: Wed, 3 Jan 2024 16:18:35 -0500 Subject: [PATCH 07/10] adding some stuff --- source/faq.txt | 11 +++++------ 1 file changed, 5 insertions(+), 6 deletions(-) diff --git a/source/faq.txt b/source/faq.txt index 698bb5bc..e2f5d9db 100644 --- a/source/faq.txt +++ b/source/faq.txt @@ -24,7 +24,7 @@ On this page, you can find frequently asked questions and their corresponding an If you can't find an answer to your question on this page, see the :ref:`rust-issues-and-help` page for information on how to report issues. -Why do I Get Errors While Connecting to MongoDB? +Why Do I Get Errors While Connecting to MongoDB? ------------------------------------------------ If you have trouble connecting to a MongoDB deployment, see the @@ -82,7 +82,7 @@ parameterized with the ``Vegetable`` type: .. code-block:: rust :copyable: true - let my_coll: Collection = client.database("db").collection("actors"); + let my_coll: Collection = client.database("db").collection("vegetables"); For more information about converting between BSON and Rust types, see the :ref:`rust-serialization` guide and the :website:`Structuring Data with Serde in Rust @@ -225,10 +225,9 @@ method. This method returns an ``Option`` that wraps either an empty value, if n concern exists, or a ``ReadConcern`` value. To access the result of ``read_concern()``, you can use the same ``match`` syntax as shown -in the preceding example. When using ``match``, replace the ``Ok(T)`` and ``Err(E)`` enum variants -with ``None`` and ``Some(T)``. Additionally, you can use the ``if let`` syntax to process only -the ``Some(T)`` variant. The following code unwraps and prints the nonempty ``read_concern()`` -return value, if it exists: +in the preceding example to process the ``None`` and ``Some(T)`` variants. Alternatively, you +can use the ``if let`` syntax to process only the ``Some(T)`` variant. The following code unwraps +and prints the nonempty ``read_concern()`` return value, if it exists: .. code-block:: rust :copyable: true From 2f1613976758b607fe90dffe9e59fe3d1b14da86 Mon Sep 17 00:00:00 2001 From: norareidy Date: Fri, 5 Jan 2024 14:57:02 -0500 Subject: [PATCH 08/10] CC feedback 2 --- source/faq.txt | 53 +++++++++++++++++++++++++------------------------- 1 file changed, 26 insertions(+), 27 deletions(-) diff --git a/source/faq.txt b/source/faq.txt index e2f5d9db..b382d34a 100644 --- a/source/faq.txt +++ b/source/faq.txt @@ -54,14 +54,14 @@ How Do I Convert Between BSON and Rust Types? --------------------------------------------- The {+driver-short+} and the BSON library use the Serde framework to perform -conversions between custom Rust types and BSON. You can install the ``serde`` -crate to access the functionality of the Serde framework. For instructions -on installing this crate, see `serde `__ in the -crates registry. +conversions between custom Rust types and BSON. You can add the ``serde`` +crate to your ``Cargo.toml`` file to access the functionality of the Serde framework. +For instructions on adding this crate, see `serde `__ +in the crates registry. After you add the crate to your application, you can model the documents in a collection -by using a custom type instead of a BSON document. The following example includes a ``derive`` -statement before the ``Vegetable`` struct definition, which instructs the driver to +by using a custom type instead of a BSON document. The following example includes the ``derive`` +attribute before the ``Vegetable`` struct definition, which instructs the driver to perform the following actions when needed: - Serialize the struct, which converts the struct to BSON @@ -76,8 +76,8 @@ perform the following actions when needed: } You can then create a ``Collection`` instance with your custom struct type as its -generic type parameter. The following example instantiates the ``my_coll`` collection -parameterized with the ``Vegetable`` type: +generic type parameter. The following example assigns a ``Collection`` instance +parameterized with the ``Vegetable`` type to the ``my_coll`` variable: .. code-block:: rust :copyable: true @@ -141,7 +141,7 @@ and using the ``try_next()`` method to iterate over ``Actor`` instances causes a To resolve the trait bounds error, identify the data type over which the cursor iterates and ensure that this data type implements the ``DeserializeOwned`` trait. -You can use a ``derive`` statement to apply the required trait bound. +You can use the ``derive`` attribute to apply the required trait bound. .. note:: Deserialize and DeserializeOwned Traits @@ -179,32 +179,26 @@ two types. The ``Result`` enum can return the following variants: -- ``Ok(T)``, which wraps the value of the result of the operation -- ``Err(E)``, which wraps an error value if the operation is unsuccessful - -The ``Option`` enum can return the following variants: - -- ``None``, which represents an empty value returned by an operation -- ``Some(T)``, which wraps a nonempty return value +- ``Ok(T)``: wraps the value of the result of the operation +- ``Err(E)``: wraps an error value if the operation is unsuccessful For example, the ``insert_one()`` method returns a ``Result`` type to wrap either a successful response or an error. -To access the result of ``insert_one()``, you can use the ``?`` operator to unwrap its -return value. If the operation is successful, the ``?`` operator unwraps the ``InsertOneResult`` -value and assigns it to the ``insert_one_result`` variable. If the operation is unsuccessful, -the ``?`` operator unwraps and returns the error value. The following code demonstrates the -syntax for using the ``?`` operator while handling an insert operation result: +To access the unwrapped result of ``insert_one()``, use the ``?`` operator. If the operation is +successful, the method returns the ``Ok(InsertOneResult)`` enum variant. In this case, the ``?`` +operator unwraps the ``InsertOneResult`` value and assigns it to the ``insert_one_result`` variable. +If the operation is unsuccessful, the method returns the ``Err(E)`` enum variant, and the ``?`` operator +unwraps and returns the error value. The following code demonstrates the syntax for using the ``?`` +operator while handling an insert operation result: .. code-block:: rust :copyable: true let insert_one_result = my_coll.insert_one(doc, None).await?; -Alternatively, you can create custom logic for handling the ``InsertOneResult`` value -depending on whether ``insert_one()`` returns the value wrapped in the ``Ok`` or the ``Err`` -variant. The following code uses the ``match`` keyword to process the ``insert_one()`` -result: +Alternatively, you can create a conditional to handle the unwrapped values of ``InsertOneResult``. +The following code uses the ``match`` keyword to process the ``insert_one()`` result: .. code-block:: rust :copyable: true @@ -220,6 +214,11 @@ result: } } +The ``Option`` enum can return the following variants: + +- ``None``: represents an empty value returned by an operation +- ``Some(T)``: wraps a non-empty return value + Some {+driver-short+} methods return an ``Option`` type, such as the ``read_concern()`` method. This method returns an ``Option`` that wraps either an empty value, if no read concern exists, or a ``ReadConcern`` value. @@ -227,7 +226,7 @@ concern exists, or a ``ReadConcern`` value. To access the result of ``read_concern()``, you can use the same ``match`` syntax as shown in the preceding example to process the ``None`` and ``Some(T)`` variants. Alternatively, you can use the ``if let`` syntax to process only the ``Some(T)`` variant. The following code unwraps -and prints the nonempty ``read_concern()`` return value, if it exists: +and prints the non-empty ``read_concern()`` return value, if it exists: .. code-block:: rust :copyable: true @@ -242,4 +241,4 @@ resources in the Rust language documentation: - `Result `__ - `Option `__ - `? Operator `__ -- `If Let `__ \ No newline at end of file +- Control Flow with `if let `__ \ No newline at end of file From 4cedd22e44730456ecb18ce4f0d7385ccf8cf4f3 Mon Sep 17 00:00:00 2001 From: norareidy Date: Fri, 5 Jan 2024 15:33:31 -0500 Subject: [PATCH 09/10] edits --- source/faq.txt | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/source/faq.txt b/source/faq.txt index b382d34a..56b3f1cd 100644 --- a/source/faq.txt +++ b/source/faq.txt @@ -186,11 +186,11 @@ For example, the ``insert_one()`` method returns a ``Result`` type to wrap eithe response or an error. To access the unwrapped result of ``insert_one()``, use the ``?`` operator. If the operation is -successful, the method returns the ``Ok(InsertOneResult)`` enum variant. In this case, the ``?`` -operator unwraps the ``InsertOneResult`` value and assigns it to the ``insert_one_result`` variable. -If the operation is unsuccessful, the method returns the ``Err(E)`` enum variant, and the ``?`` operator -unwraps and returns the error value. The following code demonstrates the syntax for using the ``?`` -operator while handling an insert operation result: +successful, the method returns the ``Ok(InsertOneResult)`` variant of the ``Result`` enum. In this +case, the ``?`` operator unwraps the ``InsertOneResult`` value and assigns it to the ``insert_one_result`` +variable. If the operation is unsuccessful, the method returns the ``Err(E)`` enum variant, and the +``?`` operator unwraps and returns the error value. The following code demonstrates the syntax for +using the ``?`` operator while handling an insert operation result: .. code-block:: rust :copyable: true From f53229a51601808ee5367a218c3b131cc453a689 Mon Sep 17 00:00:00 2001 From: norareidy Date: Fri, 5 Jan 2024 15:45:10 -0500 Subject: [PATCH 10/10] small thing --- source/faq.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/faq.txt b/source/faq.txt index 56b3f1cd..57189d07 100644 --- a/source/faq.txt +++ b/source/faq.txt @@ -241,4 +241,4 @@ resources in the Rust language documentation: - `Result `__ - `Option `__ - `? Operator `__ -- Control Flow with `if let `__ \ No newline at end of file +- `Concise Control Flow with if let `__ \ No newline at end of file