From 2b80ac78f5061cf02ec6f092065c2e96ab1cb6a7 Mon Sep 17 00:00:00 2001 From: norareidy Date: Thu, 29 May 2025 11:18:46 -0400 Subject: [PATCH 1/6] DOCSP-47055: Collation --- source/includes/collation.rst | 93 +++++++++++++++++++++++++++++++++++ 1 file changed, 93 insertions(+) create mode 100644 source/includes/collation.rst diff --git a/source/includes/collation.rst b/source/includes/collation.rst new file mode 100644 index 00000000..773891e6 --- /dev/null +++ b/source/includes/collation.rst @@ -0,0 +1,93 @@ +To specify a collation for your operation, pass an ``$options`` array +parameter that sets the ``collation`` option to the operation method. +Assign the ``collation`` option to an array that configures the collation +rules. + +The following table describes the fields you can set to configure +the collation: + +.. list-table:: + :widths: 30 70 + :header-rows: 1 + + * - Field + - Description + + * - ``locale`` + - | *(Required)* 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. + + * - ``caseLevel`` + - | *(Optional)* Specifies whether to include case comparison. + | + | When set to ``true``, the comparison behavior depends on the value of + the ``strength`` field: + | + | - If ``strength`` is ``1``, the {+library-short+} compares base + characters and case. + | - If ``strength`` is ``2``, the {+library-short+} compares base + characters, diacritics, other secondary differences, and case. + | - If ``strength`` is any other value, this field is ignored. + | + | When set to ``false``, the {+library-short+} doesn't include case comparison at + strength level ``1`` or ``2``. + | + | **Data Type**: {+bool-data-type+} + | **Default**: ``false`` + + * - ``caseFirst`` + - | *(Optional)* Specifies the sort order of case differences during tertiary + level comparisons. + | + | **Data Type**: {+string-data-type+} + | **Default**: ``"off"`` + + * - ``strength`` + - | *(Optional)* Specifies the level of comparison to perform, as defined in the + `ICU documentation `__. + | + | **Data Type**: {+int-data-type+} + | **Default**: ``3`` + + * - ``numericOrdering`` + - | *(Optional)* Specifies whether the driver compares numeric strings as numbers. + | + | If set to ``true``, the {+library-short+} compares numeric strings as numbers. + For example, when comparing the strings "10" and "2", the library uses the + strings' numeric values and treats "10" as greater than "2". + | + | If set to ``false``, the {+library-short+} compares numeric strings + as strings. For example, when comparing the strings "10" and "2", the library + compares one character at a time and treats "10" as less than "2". + | + | For more information, see :manual:`Collation Restrictions ` + in the {+mdb-server+} manual. + | + | **Data Type**: {+bool-data-type+} + | **Default**: ``false`` + + * - ``alternate`` + - | *(Optional)* Specifies whether the library considers whitespace and punctuation as base + characters for comparison purposes. + | + | **Data Type**: {+string-data-type+} + | **Default**: ``"non-ignorable"`` + + * - ``maxVariable`` + - | *(Optional)* Specifies which characters the library considers ignorable when + the ``alternate`` field is set to ``"shifted"``. + | + | **Data Type**: {+string-data-type+} + | **Default**: ``"punct"`` + + * - ``backwards`` + - | *(Optional)* Specifies whether strings containing diacritics sort from the back of the string + to the front. + | + | **Data Type**: {+bool-data-type+} + | **Default**: ``false`` + +To learn more about collation, see the :manual:`Collation ` +entry in the {+mdb-server+} manual. \ No newline at end of file From 637c1e090df7e8e2182a97ac599d5ae761fc9bb4 Mon Sep 17 00:00:00 2001 From: norareidy Date: Thu, 29 May 2025 12:04:16 -0400 Subject: [PATCH 2/6] add to each page --- source/crud/delete.txt | 11 +++++++++-- source/crud/query/count.txt | 10 +++++++++- source/crud/query/distinct.txt | 10 +++++++++- source/crud/query/retrieve.txt | 10 +++++++++- source/crud/replace.txt | 11 +++++++++-- source/crud/update.txt | 11 +++++++++-- source/monitoring-logging/change-streams.txt | 10 +++++++++- 7 files changed, 63 insertions(+), 10 deletions(-) diff --git a/source/crud/delete.txt b/source/crud/delete.txt index 2dd0cec1..9a48cee4 100644 --- a/source/crud/delete.txt +++ b/source/crud/delete.txt @@ -101,8 +101,8 @@ options you can set in the array: * - ``collation`` - | Specifies the kind of language collation to use when comparing - strings. For more information, see :manual:`Collation ` - in the {+mdb-server+} manual. + strings. To learn more, see the :ref:`php-delete-collation` section + of this page. * - ``writeConcern`` - | Sets the write concern for the operation. This option defaults to @@ -152,6 +152,13 @@ operation: the preceding example, the library deletes only the first document that has a ``name`` value containing ``'Mongo'``. +.. _php-delete-collation: + +Collation +~~~~~~~~~ + +.. include:: /includes/collation.rst + Return Value ------------ diff --git a/source/crud/query/count.txt b/source/crud/query/count.txt index 19765deb..59e3dd65 100644 --- a/source/crud/query/count.txt +++ b/source/crud/query/count.txt @@ -120,7 +120,8 @@ describes some options you can set to customize the count operation: - Description * - ``collation`` - - | The collation to use for the operation. + - | The collation to use for the operation. To learn more, + see the :ref:`php-count-collation` section of this page. | **Type**: ``array|object`` * - ``hint`` @@ -166,6 +167,13 @@ operation to count a maximum of ``100`` results: Number of companies with 50 employees: 100 +.. _php-count-collation: + +Collation +````````` + +.. include:: /includes/collation.rst + .. _php-estimated-count: Retrieve an Estimated Count diff --git a/source/crud/query/distinct.txt b/source/crud/query/distinct.txt index 8a71ca01..90f99960 100644 --- a/source/crud/query/distinct.txt +++ b/source/crud/query/distinct.txt @@ -123,7 +123,8 @@ options you can set to customize the operation: - Description * - ``collation`` - - | The collation to use for the operation. + - | The collation to use for the operation. To learn more, see the + :ref:`php-distinct-collation` section of this page. | **Type**: ``array|object`` * - ``maxTimeMS`` @@ -169,6 +170,13 @@ in an options array to add a comment to the operation: "Angie'S Cafe Pizza" ... +.. _php-distinct-collation: + +Collation +````````` + +.. include:: /includes/collation.rst + API Documentation ----------------- diff --git a/source/crud/query/retrieve.txt b/source/crud/query/retrieve.txt index 4e76dff1..755e3a4f 100644 --- a/source/crud/query/retrieve.txt +++ b/source/crud/query/retrieve.txt @@ -190,7 +190,8 @@ you can set in the array: * - ``collation`` - | The collation to use for the operation. The default value is the collation - specified for the collection. + specified for the collection. To learn more, see the :ref:`php-retrieve-collation` + section of this page. | **Type**: ``array|object`` * - ``comment`` @@ -233,6 +234,13 @@ For a full list of options, see the API documentation for the `findOne() <{+api+}/method/MongoDBCollection-findOne/#parameters>`__ and `find() <{+api+}/method/MongoDBCollection-find/#parameters>`__ parameters. +.. _php-retrieve-collation: + +Collation +````````` + +.. include:: /includes/collation.rst + .. _php-retrieve-additional-information: Additional Information diff --git a/source/crud/replace.txt b/source/crud/replace.txt index 5c3ba370..e84a3739 100644 --- a/source/crud/replace.txt +++ b/source/crud/replace.txt @@ -159,8 +159,8 @@ table describes some options you can set in the array: * - ``collation`` - | Specifies the kind of language collation to use when sorting - results. For more information, see :manual:`Collation ` - in the {+mdb-server+} manual. + results. To learn more, see the :ref:`php-replace-collation` + section of this page. * - ``hint`` - | Gets or sets the index to scan for documents. @@ -197,6 +197,13 @@ filter doesn't match any existing documents: :language: php :copyable: +.. _php-replace-collation: + +Collation +~~~~~~~~~ + +.. include:: /includes/collation.rst + Additional Information ---------------------- diff --git a/source/crud/update.txt b/source/crud/update.txt index b6e22d02..103e6ce1 100644 --- a/source/crud/update.txt +++ b/source/crud/update.txt @@ -125,8 +125,8 @@ describes some options you can set in the array: * - ``collation`` - | Specifies the kind of language collation to use when sorting - results. For more information, see :manual:`Collation ` - in the {+mdb-server+} manual. + results. To learn more, see the :ref:`php-update-collation` section + of this page. * - ``arrayFilters`` - | Specifies which array elements an update applies to if the operation modifies @@ -166,6 +166,13 @@ match any existing documents. :language: php :dedent: +.. _php-update-collation: + +Collation +````````` + +.. include:: /includes/collation.rst + Return Value ~~~~~~~~~~~~ diff --git a/source/monitoring-logging/change-streams.txt b/source/monitoring-logging/change-streams.txt index 35cf9f5a..c1256474 100644 --- a/source/monitoring-logging/change-streams.txt +++ b/source/monitoring-logging/change-streams.txt @@ -174,7 +174,8 @@ can set in the array: | This option is mutually exclusive with ``startAfter`` and ``resumeAfter``. * - ``collation`` - - | Sets the collation to use for the change stream cursor. + - | Sets the collation to use for the change stream cursor. To learn more, + see the :ref:`php-change-stream-collation` section of this page. For a full list of ``watch()`` options, see `MongoDB\\Collection::watch() <{+api+}/method/MongoDBCollection-watch/>`__ in the API @@ -255,6 +256,13 @@ output: :manual:`Change Streams with Document Pre- and Post-Images ` in the {+mdb-server+} manual. +.. _php-change-stream-collation: + +Collation +~~~~~~~~~ + +.. include:: /includes/collation.rst + Additional Information ---------------------- From 0ed9c30f62936193985701fa3693bdea50c8b70c Mon Sep 17 00:00:00 2001 From: norareidy Date: Thu, 29 May 2025 12:07:10 -0400 Subject: [PATCH 3/6] edit --- source/includes/collation.rst | 2 ++ 1 file changed, 2 insertions(+) diff --git a/source/includes/collation.rst b/source/includes/collation.rst index 773891e6..5331e6a5 100644 --- a/source/includes/collation.rst +++ b/source/includes/collation.rst @@ -18,6 +18,8 @@ the collation: list of supported locales, see :manual:`Collation Locales and Default Parameters ` in the {+mdb-server+} Manual. + | + | **Data Type**: {+string-data-type+} * - ``caseLevel`` - | *(Optional)* Specifies whether to include case comparison. From f5b19d430a2ad885006b4edd0729758af14e7db1 Mon Sep 17 00:00:00 2001 From: norareidy Date: Thu, 29 May 2025 12:11:44 -0400 Subject: [PATCH 4/6] edits --- source/crud/delete.txt | 14 +++++++------- source/crud/replace.txt | 14 +++++++------- source/includes/collation.rst | 8 ++++---- 3 files changed, 18 insertions(+), 18 deletions(-) diff --git a/source/crud/delete.txt b/source/crud/delete.txt index 9a48cee4..437ad491 100644 --- a/source/crud/delete.txt +++ b/source/crud/delete.txt @@ -132,6 +132,13 @@ options you can set in the array: fields ` guide in the {+mdb-server+} manual. +.. _php-delete-collation: + +Collation +~~~~~~~~~ + +.. include:: /includes/collation.rst + Example ~~~~~~~ @@ -152,13 +159,6 @@ operation: the preceding example, the library deletes only the first document that has a ``name`` value containing ``'Mongo'``. -.. _php-delete-collation: - -Collation -~~~~~~~~~ - -.. include:: /includes/collation.rst - Return Value ------------ diff --git a/source/crud/replace.txt b/source/crud/replace.txt index e84a3739..b277192d 100644 --- a/source/crud/replace.txt +++ b/source/crud/replace.txt @@ -182,6 +182,13 @@ table describes some options you can set in the array: fields ` guide in the {+mdb-server+} manual. +.. _php-replace-collation: + +Collation +~~~~~~~~~ + +.. include:: /includes/collation.rst + Example ~~~~~~~ @@ -197,13 +204,6 @@ filter doesn't match any existing documents: :language: php :copyable: -.. _php-replace-collation: - -Collation -~~~~~~~~~ - -.. include:: /includes/collation.rst - Additional Information ---------------------- diff --git a/source/includes/collation.rst b/source/includes/collation.rst index 5331e6a5..3ebffbe8 100644 --- a/source/includes/collation.rst +++ b/source/includes/collation.rst @@ -17,7 +17,7 @@ the collation: - | *(Required)* 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. + in the {+mdb-server+} manual. | | **Data Type**: {+string-data-type+} @@ -27,11 +27,11 @@ the collation: | When set to ``true``, the comparison behavior depends on the value of the ``strength`` field: | - | - If ``strength`` is ``1``, the {+library-short+} compares base + - If ``strength`` is ``1``, the {+library-short+} compares base characters and case. - | - If ``strength`` is ``2``, the {+library-short+} compares base + - If ``strength`` is ``2``, the {+library-short+} compares base characters, diacritics, other secondary differences, and case. - | - If ``strength`` is any other value, this field is ignored. + - If ``strength`` is any other value, this field is ignored. | | When set to ``false``, the {+library-short+} doesn't include case comparison at strength level ``1`` or ``2``. From 8443a439b3cf1b2208a0e3462441bd84b99e099a Mon Sep 17 00:00:00 2001 From: norareidy Date: Thu, 29 May 2025 13:47:29 -0400 Subject: [PATCH 5/6] list format --- source/includes/collation.rst | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/source/includes/collation.rst b/source/includes/collation.rst index 3ebffbe8..f9db522d 100644 --- a/source/includes/collation.rst +++ b/source/includes/collation.rst @@ -29,10 +29,12 @@ the collation: | - If ``strength`` is ``1``, the {+library-short+} compares base characters and case. + | - If ``strength`` is ``2``, the {+library-short+} compares base characters, diacritics, other secondary differences, and case. - - If ``strength`` is any other value, this field is ignored. | + - If ``strength`` is any other value, this field is ignored. + | When set to ``false``, the {+library-short+} doesn't include case comparison at strength level ``1`` or ``2``. | From 24c1e17351e07be0ecc344e7fbb760bf8597647a Mon Sep 17 00:00:00 2001 From: norareidy Date: Thu, 29 May 2025 14:36:35 -0400 Subject: [PATCH 6/6] SA feedback --- 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 f9db522d..bed2508b 100644 --- a/source/includes/collation.rst +++ b/source/includes/collation.rst @@ -27,14 +27,14 @@ the collation: | When set to ``true``, the comparison behavior depends on the value of the ``strength`` field: | - - If ``strength`` is ``1``, the {+library-short+} compares base - characters and case. + | - If ``strength`` is ``1``, the {+library-short+} compares base + | characters and case. | - - If ``strength`` is ``2``, the {+library-short+} compares base - characters, diacritics, other secondary differences, and case. + | - If ``strength`` is ``2``, the {+library-short+} compares base + | characters, diacritics, other secondary differences, and case. + | + | - If ``strength`` is any other value, this field is ignored. | - - If ``strength`` is any other value, this field is ignored. - | When set to ``false``, the {+library-short+} doesn't include case comparison at strength level ``1`` or ``2``. | @@ -93,5 +93,5 @@ the collation: | **Data Type**: {+bool-data-type+} | **Default**: ``false`` -To learn more about collation, see the :manual:`Collation ` +To learn more about collation and the possible values for each field, see the :manual:`Collation ` entry in the {+mdb-server+} manual. \ No newline at end of file