From eef322949867878418c70255590695b5043d3410 Mon Sep 17 00:00:00 2001 From: Mike Woofter <108414937+mongoKart@users.noreply.github.com> Date: Wed, 7 May 2025 14:34:28 -0500 Subject: [PATCH 1/4] first draft --- source/crud/bulk-write.txt | 20 ++-- source/crud/delete.txt | 12 +- source/crud/query/count.txt | 10 +- source/crud/query/distinct.txt | 11 +- source/crud/query/find.txt | 10 +- source/crud/replace.txt | 11 +- source/includes/collation.rst | 110 ++++++++++++++++++ .../includes/page-templates/update/update.rst | 11 +- .../logging-and-monitoring/change-streams.txt | 10 +- 9 files changed, 186 insertions(+), 19 deletions(-) create mode 100644 source/includes/collation.rst diff --git a/source/crud/bulk-write.txt b/source/crud/bulk-write.txt index fb7a0963..b8e746dc 100644 --- a/source/crud/bulk-write.txt +++ b/source/crud/bulk-write.txt @@ -133,8 +133,7 @@ parameters: * - ``collation`` - | *Optional.* The language collation to use when sorting results. See the - :manual:`{+mdb+server+} manual` - for more information. + :ref:`` section of this page for more information. | | **Data Type:** `Collation <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.Collation.html>`__ | **Default:** ``null`` @@ -228,9 +227,8 @@ constructor accepts the following parameters: | **Data Type:** ``TDocument`` * - ``collation`` - - | *Optional.* The language collation to use when sorting results. See - the :manual:`{+mdb-server+} manual` - for more information. + - | *Optional.* The language collation to use when sorting results. See the + :ref:`` section of this page for more information. | | **Data Type:** `Collation <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.Collation.html>`__ | **Default:** ``null`` @@ -298,9 +296,8 @@ parameters: | **Data Type:** `FilterDefinition <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.FilterDefinition-1.html>`__ * - ``collation`` - - | *Optional.* The language collation to use when sorting results. See - the :manual:`{+mdb-server+} manual` - for more information. + - | *Optional.* The language collation to use when sorting results. See the + :ref:`` section of this page for more information. | | **Data Type:** `Collation <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.Collation.html>`__ | **Default:** ``null`` @@ -470,6 +467,13 @@ a delete operation: :copyable: :dedent: 8 +.. _csharp-bulk-write-collation: + +Collation +~~~~~~~~~ + +.. include:: /includes/collation.rst + Return Value ------------ diff --git a/source/crud/delete.txt b/source/crud/delete.txt index 8b91da80..83840696 100644 --- a/source/crud/delete.txt +++ b/source/crud/delete.txt @@ -139,9 +139,8 @@ following properties: * - ``Collation`` - | Gets or sets the type of language collation to use when sorting - results. See :manual:`the delete - statements` - for more information. + results. See the :ref:`` section of this page for more + information. * - ``Comment`` - | Gets or sets the comment for the operation. See :manual:`the delete command @@ -158,6 +157,13 @@ following properties: fields` for more information. +.. _csharp-delete-collation: + +Collation +~~~~~~~~~ + +.. include:: /includes/collation.rst + Example ~~~~~~~ diff --git a/source/crud/query/count.txt b/source/crud/query/count.txt index cc2e4aa1..1b4c8bdf 100644 --- a/source/crud/query/count.txt +++ b/source/crud/query/count.txt @@ -98,7 +98,8 @@ You can set the following properties in a ``CountOptions`` object: - Description * - ``Collation`` - - | The type of language collation to use when sorting results. + - | The type of language collation to use when sorting results. See the + :ref:`` section of this page for more information. | Default: ``null`` * - ``Hint`` @@ -132,6 +133,13 @@ You can set the following properties in a ``CountOptions`` object: CountOptions opts = new CountOptions(){Hint = "_id_"}; var count = collection.CountDocuments(filter, opts); +.. _csharp-count-collation: + +Collation +~~~~~~~~~ + +.. include:: /includes/collation.rst + .. _csharp-estimated-count: Estimated Count diff --git a/source/crud/query/distinct.txt b/source/crud/query/distinct.txt index a3af7165..9aff824f 100644 --- a/source/crud/query/distinct.txt +++ b/source/crud/query/distinct.txt @@ -180,7 +180,9 @@ describes the properties you can set on a ``DistinctOptions`` instance: - Description * - ``Collation`` - - | Sets the collation to use for the operation. + - | Sets the collation to use for the operation. See the + :ref:`` section of this page for more information. + | Default: ``null`` | **Data type**: `Collation <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.DistinctOptions.Collation.html>`__ * - ``MaxTime`` @@ -249,6 +251,13 @@ corresponding code. Angie'S Cafe Pizza ... +.. _csharp-distinct-collation: + +Collation +~~~~~~~~~ + +.. include:: /includes/collation.rst + API Documentation ----------------- diff --git a/source/crud/query/find.txt b/source/crud/query/find.txt index f5f2526e..64ffcb47 100644 --- a/source/crud/query/find.txt +++ b/source/crud/query/find.txt @@ -208,7 +208,8 @@ You can configure the commonly used options with the following methods: - | Gets or sets the number of documents to hold in a cursor at a given time. * - ``Collation`` - - | Sets the collation options. + - | Sets the collation options. See the + :ref:`` section of this page for more information. * - ``Comment`` - | Sets the comment to the query. To learn more about query comments, @@ -223,6 +224,13 @@ You can configure the commonly used options with the following methods: To see a full list of available options, see `FindOptions Properties <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.FindOptions.html>`__. +.. _csharp-find-collation: + +Collation +~~~~~~~~~ + +.. include:: /includes/collation.rst + Example ~~~~~~~ diff --git a/source/crud/replace.txt b/source/crud/replace.txt index c094116b..b430ae32 100644 --- a/source/crud/replace.txt +++ b/source/crud/replace.txt @@ -138,8 +138,8 @@ The ``ReplaceOptions`` class contains the following properties: * - ``Collation`` - Specifies the kind of language collation to use when sorting - results. See :manual:`the {+mdb-server+} manual ` - for more information on collation. + results. See the :ref:`` section of this page for more + information. **Data Type:** `Collation <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.Collation.html>`__ @@ -199,6 +199,13 @@ code. :start-after: // start-replace-one-async-with-options :end-before: // end-replace-one-async-with-options +.. _csharp-replace-collation: + +Collation +~~~~~~~~~ + +.. include:: /includes/collation.rst + Return Value ~~~~~~~~~~~~ diff --git a/source/includes/collation.rst b/source/includes/collation.rst new file mode 100644 index 00000000..043de21c --- /dev/null +++ b/source/includes/collation.rst @@ -0,0 +1,110 @@ +To configure collation for your operation, create an instance of the +`Collation <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.Collation.html>`__ class. + +The following table describes the parameters that the ``Collation`` constructor accepts. +It also lists the corresponding class property that you can use to read each +setting's value. + +.. list-table:: + :header-rows: 1 + :widths: 30 40 30 + + * - Parameter + - Description + - Class Property + + * - ``locale`` + - | Specifies the International Components for Unicode (ICU) locale. For a list of + supported locales, + see :manual:`Collation Locales and Default Parameters `. + in the {+mdb-server+} Manual. + | + | If you want to use simple binary comparison, use the ``Collation.Simple`` static + property to return a ``Collation`` object with the ``locale`` set to ``"simple"``. + | **Data Type**: {+string-data-type+} + - ``Locale`` + + * - ``alternate`` + - | Optional. Specifies whether the driver considers whitespace and punctuation as base + characters for purposes of comparison. + | + | **Data Type**: `CollationAlternate <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.CollationAlternate.html>`__ + | **Default**: ``CollationAlternate.NonIgnorable`` (spaces and punctuation are + considered base characters) + - ``Alternate`` + + * - ``backwards`` + - | Optional. Specifies whether strings containing diacritics sort from the back of the string + to the front. + | + | **Data Type**: {+bool-data-type+} + | **Default**: ``false`` + - ``Backwards`` + + * - ``caseFirst`` + - | Optional. Specifies the sort order of case differences during tertiary level comparisons. + | + | **Data Type**: `CollationCaseFirst <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.CollationCaseFirst.html>`__ + | **Default**: ``CollationCaseFirst.Off`` + - ``CaseFirst`` + + * - ``caseLevel`` + - | Optional. Specifies whether to include case comparison at strength level ``Primary`` or + ``Secondary``. + | + | When this argument is ``true``: + | + | - If ``Strength`` is ``CollationStrength.Primary``, the driver compares base + characters and case. + | - If ``Strength`` is ``CollationStrength.Secondary``, the driver compares base + characters, diacritics, other secondary differences, and case. + | + | When this argument is ``false``, the driver doesn't include case comparison at + strength level 1 or 2. + | + | **Data Type**: {+bool-data-type+} + | **Default**: ``false`` + - ``CaseLevel`` + + * - ``maxVariable`` + - | Optional. Specifies which characters the driver considers ignorable when + ``Alternate`` is ``CollationAlternate.Shifted``. + | + | **Data Type**: `CollationMaxVariable <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.CollationMaxVariable.html>`__ + | **Default**: ``CollationMaxVariable.Punctuation`` (the driver ignores punctuation + and spaces) + - ``MaxVariable`` + + * - ``normalization`` + - | Optional. Specifies whether the driver normalizes text as needed. + | + | Most text doesn't require normalization. + | + | **Data Type**: ``{+bool-data-type+}`` + | **Default**: ``false`` + - ``Normalization`` + + * - ``numericOrdering`` + - | Optional. Specifies whether the driver compares numeric strings as numbers. + | + | If this argument is ``true``, the driver compares numeric strings as numbers. + For example, "10" is greater than "2". If this argument is ``false`` or excluded, + the driver compares numeric strings as strings. For example, "10" is less than "2". + | + | For more information, see :manual:`Collation ` + in the {+mdb-server+} manual. + | + | **Data Type**: ``{+bool-data-type+}`` + | **Default**: ``false`` + - ``NumericOrdering`` + + * - ``strength`` + - Optional. Specifies the level of comparison to perform, as defined in the + `ICU documentation `__. + | + | **Data Type**: `CollationStrength <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.CollationStrength.html>`__ + | **Default**: ``CollationStrength.Tertiary`` + - ``Strength`` + +For more information about collation, see the :manual:`Collation ` +page in the {+mdb-server+} manual. \ No newline at end of file diff --git a/source/includes/page-templates/update/update.rst b/source/includes/page-templates/update/update.rst index c6087ced..e21002c7 100644 --- a/source/includes/page-templates/update/update.rst +++ b/source/includes/page-templates/update/update.rst @@ -165,8 +165,8 @@ The ``UpdateOptions`` class contains the following properties: * - ``Collation`` - Specifies the kind of language collation to use when sorting - results. See :manual:`the {+mdb-server+} manual` - for more information on collation. + results. See the + :ref:`` section of this page for more information. **Data Type:** `Collation <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.Collation.html>`__ @@ -199,6 +199,13 @@ The ``UpdateOptions`` class contains the following properties: **Data Type:** `BsonDocument <{+new-api-root+}/MongoDB.Bson/MongoDB.Bson.BsonDocument.html>`__ +.. _csharp-update-collation: + +Collation +~~~~~~~~~ + +.. include:: /includes/collation.rst + Return Value ------------ diff --git a/source/logging-and-monitoring/change-streams.txt b/source/logging-and-monitoring/change-streams.txt index e2fcc359..95efdbd7 100644 --- a/source/logging-and-monitoring/change-streams.txt +++ b/source/logging-and-monitoring/change-streams.txt @@ -289,11 +289,19 @@ of ``Watch()`` and ``WatchAsync()``: response from the MongoDB cluster. * - ``Collation`` - - | Specifies the collation to use for the change stream cursor. + - | Specifies the collation to use for the change stream cursor. See the + :ref:`` section of this page for more information. * - ``Comment`` - | Attaches a comment to the operation. +.. _csharp-change-stream-collation: + +Collation +~~~~~~~~~ + +.. include:: /includes/collation.rst + .. _csharp-change-stream-pre-post-image: Include Pre-Images and Post-Images From 02a59e2ca00fb859216651a20b7ad714bde98519 Mon Sep 17 00:00:00 2001 From: Mike Woofter <108414937+mongoKart@users.noreply.github.com> Date: Wed, 7 May 2025 14:41:15 -0500 Subject: [PATCH 2/4] table fixes --- source/includes/collation.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/source/includes/collation.rst b/source/includes/collation.rst index 043de21c..a70a4232 100644 --- a/source/includes/collation.rst +++ b/source/includes/collation.rst @@ -7,7 +7,7 @@ setting's value. .. list-table:: :header-rows: 1 - :widths: 30 40 30 + :widths: 20 60 20 * - Parameter - Description @@ -99,8 +99,8 @@ setting's value. - ``NumericOrdering`` * - ``strength`` - - Optional. Specifies the level of comparison to perform, as defined in the - `ICU documentation `__. + - | Optional. Specifies the level of comparison to perform, as defined in the + `ICU documentation `__. | | **Data Type**: `CollationStrength <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.CollationStrength.html>`__ | **Default**: ``CollationStrength.Tertiary`` From 169591e40adc816246b7fac1e675576d4b5a8bae Mon Sep 17 00:00:00 2001 From: Mike Woofter <108414937+mongoKart@users.noreply.github.com> Date: Wed, 7 May 2025 14:47:16 -0500 Subject: [PATCH 3/4] fixes --- source/includes/collation.rst | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/source/includes/collation.rst b/source/includes/collation.rst index a70a4232..46cd7580 100644 --- a/source/includes/collation.rst +++ b/source/includes/collation.rst @@ -16,7 +16,7 @@ setting's value. * - ``locale`` - | Specifies the International Components for Unicode (ICU) locale. For a list of supported locales, - see :manual:`Collation Locales and Default Parameters `. + see :manual:`Collation Locales and Default Parameters ` in the {+mdb-server+} Manual. | | If you want to use simple binary comparison, use the ``Collation.Simple`` static @@ -54,13 +54,13 @@ setting's value. | | When this argument is ``true``: | - | - If ``Strength`` is ``CollationStrength.Primary``, the driver compares base + | - If the strength is ``Primary``, the driver compares base characters and case. - | - If ``Strength`` is ``CollationStrength.Secondary``, the driver compares base + | - If the strength is ``Secondary``, the driver compares base characters, diacritics, other secondary differences, and case. | | When this argument is ``false``, the driver doesn't include case comparison at - strength level 1 or 2. + strength level ``Primary`` or ``Secondary``. | | **Data Type**: {+bool-data-type+} | **Default**: ``false`` @@ -80,7 +80,7 @@ setting's value. | | Most text doesn't require normalization. | - | **Data Type**: ``{+bool-data-type+}`` + | **Data Type**: {+bool-data-type+} | **Default**: ``false`` - ``Normalization`` @@ -91,10 +91,10 @@ setting's value. For example, "10" is greater than "2". If this argument is ``false`` or excluded, the driver compares numeric strings as strings. For example, "10" is less than "2". | - | For more information, see :manual:`Collation ` + | For more information, see :manual:`Collation Restrictions ` in the {+mdb-server+} manual. | - | **Data Type**: ``{+bool-data-type+}`` + | **Data Type**: {+bool-data-type+} | **Default**: ``false`` - ``NumericOrdering`` From ed9d6bc831ae23d4d5b9e00af6a60a67778a28de Mon Sep 17 00:00:00 2001 From: Mike Woofter <108414937+mongoKart@users.noreply.github.com> Date: Thu, 8 May 2025 16:26:46 -0500 Subject: [PATCH 4/4] rm review --- source/includes/collation.rst | 107 ++++++++++++++++++---------------- 1 file changed, 57 insertions(+), 50 deletions(-) diff --git a/source/includes/collation.rst b/source/includes/collation.rst index 46cd7580..e944268c 100644 --- a/source/includes/collation.rst +++ b/source/includes/collation.rst @@ -24,51 +24,71 @@ setting's value. | **Data Type**: {+string-data-type+} - ``Locale`` - * - ``alternate`` - - | Optional. Specifies whether the driver considers whitespace and punctuation as base - characters for purposes of comparison. + * - ``caseLevel`` + - | *(Optional)* Specifies whether to include case comparison. | - | **Data Type**: `CollationAlternate <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.CollationAlternate.html>`__ - | **Default**: ``CollationAlternate.NonIgnorable`` (spaces and punctuation are - considered base characters) - - ``Alternate`` - - * - ``backwards`` - - | Optional. Specifies whether strings containing diacritics sort from the back of the string - to the front. + | When this argument is ``true``, the driver's behavior depends on the value of + the ``strength`` argument: + | + | - If ``strength`` is ``CollationStrength.Primary``, the driver compares base + characters and case. + | - If ``strength`` is ``CollationStrength.Secondary``, the driver compares base + characters, diacritics, other secondary differences, and case. + | - If ``strength`` is any other value, this argument is ignored. + | + | When this argument is ``false``, the driver doesn't include case comparison at + strength level ``Primary`` or ``Secondary``. | | **Data Type**: {+bool-data-type+} | **Default**: ``false`` - - ``Backwards`` + - ``CaseLevel`` * - ``caseFirst`` - - | Optional. Specifies the sort order of case differences during tertiary level comparisons. + - | *(Optional)* Specifies the sort order of case differences during tertiary level comparisons. | | **Data Type**: `CollationCaseFirst <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.CollationCaseFirst.html>`__ | **Default**: ``CollationCaseFirst.Off`` - ``CaseFirst`` - * - ``caseLevel`` - - | Optional. Specifies whether to include case comparison at strength level ``Primary`` or - ``Secondary``. - | - | When this argument is ``true``: + * - ``strength`` + - | *(Optional)* Specifies the level of comparison to perform, as defined in the + `ICU documentation `__. | - | - If the strength is ``Primary``, the driver compares base - characters and case. - | - If the strength is ``Secondary``, the driver compares base - characters, diacritics, other secondary differences, and case. + | **Data Type**: `CollationStrength <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.CollationStrength.html>`__ + | **Default**: ``CollationStrength.Tertiary`` + - ``Strength`` + + * - ``numericOrdering`` + - | *(Optional)* Specifies whether the driver compares numeric strings as numbers. + | + | If this argument is ``true``, the driver compares numeric strings as numbers. + For example, when comparing the strings "10" and "2", the driver treats the values + as 10 and 2, and finds 10 to be greater. + | + | If this argument is ``false`` or excluded, the driver compares numeric strings + as strings. For example, when comparing the strings "10" and "2", the driver + compares one character at a time. Because "1" is less than "2", the driver finds + "10" to be less than "2". | - | When this argument is ``false``, the driver doesn't include case comparison at - strength level ``Primary`` or ``Secondary``. + | For more information, see :manual:`Collation Restrictions ` + in the {+mdb-server+} manual. | - | **Data Type**: {+bool-data-type+} + | **Data Type**: {+bool-data-type+} | **Default**: ``false`` - - ``CaseLevel`` + - ``NumericOrdering`` + + * - ``alternate`` + - | *(Optional)* Specifies whether the driver considers whitespace and punctuation as base + characters for purposes of comparison. + | + | **Data Type**: `CollationAlternate <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.CollationAlternate.html>`__ + | **Default**: ``CollationAlternate.NonIgnorable`` (spaces and punctuation are + considered base characters) + - ``Alternate`` * - ``maxVariable`` - - | Optional. Specifies which characters the driver considers ignorable when - ``Alternate`` is ``CollationAlternate.Shifted``. + - | *(Optional)* Specifies which characters the driver considers ignorable when + the ``alternate`` argument is ``CollationAlternate.Shifted``. | | **Data Type**: `CollationMaxVariable <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.CollationMaxVariable.html>`__ | **Default**: ``CollationMaxVariable.Punctuation`` (the driver ignores punctuation @@ -76,35 +96,22 @@ setting's value. - ``MaxVariable`` * - ``normalization`` - - | Optional. Specifies whether the driver normalizes text as needed. + - | *(Optional)* Specifies whether the driver normalizes text as needed. | - | Most text doesn't require normalization. + | Most text doesn't require normalization. For more information about + normalization, see the `ICU documentation `__. | | **Data Type**: {+bool-data-type+} | **Default**: ``false`` - ``Normalization`` - * - ``numericOrdering`` - - | Optional. Specifies whether the driver compares numeric strings as numbers. - | - | If this argument is ``true``, the driver compares numeric strings as numbers. - For example, "10" is greater than "2". If this argument is ``false`` or excluded, - the driver compares numeric strings as strings. For example, "10" is less than "2". - | - | For more information, see :manual:`Collation Restrictions ` - in the {+mdb-server+} manual. + * - ``backwards`` + - | *(Optional)* Specifies whether strings containing diacritics sort from the back of the string + to the front. | - | **Data Type**: {+bool-data-type+} + | **Data Type**: {+bool-data-type+} | **Default**: ``false`` - - ``NumericOrdering`` - - * - ``strength`` - - | Optional. Specifies the level of comparison to perform, as defined in the - `ICU documentation `__. - | - | **Data Type**: `CollationStrength <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.CollationStrength.html>`__ - | **Default**: ``CollationStrength.Tertiary`` - - ``Strength`` + - ``Backwards`` -For more information about collation, see the :manual:`Collation ` +For more information about collation, see the :manual:`Collation ` page in the {+mdb-server+} manual. \ No newline at end of file