DOCSP-19919 Mention limitations to collation document's 'numericOrdering' option (#289)

* DOCSP-19919 init

* code-block none

* *

* Added code example in restrictions section

* remove the

* code block indent fix

* remove comma

* Apply suggestions from code review

Co-authored-by: jeff-allen-mongo <[email protected]>

* *

* Add addition bullet for clarity

* Address Kyle comments #1

* add 3 docs back to insert

* numericOrder -> numericOrdering

Co-authored-by: jeff-allen-mongo <[email protected]>

Author: ianf-mongodb

source/includes/extracts-collation.yaml

@@ -43,7 +43,7 @@ content: |
 
    The collation option has the following syntax:
 
-   .. code-block:: javascript
+   .. code-block:: none
 
       collation: {
          locale: <string>,
@@ -62,7 +62,7 @@ content: |
 ---
 ref: collation-document
 content: |
-   .. code-block:: javascript
+   .. code-block:: none
 
       {
          locale: <string>,

source/reference/collation.txt

@@ -119,10 +119,10 @@ parameters and the locales they are associated with, see
 
      - boolean
 
-     - Optional. Flag that determines whether to include case comparison at
-       ``strength`` level ``1`` or ``2``.
+     - Optional. Flag that determines whether to include case comparison 
+       at ``strength`` level ``1`` or ``2``.
 
-       If ``true``, include case comparison; i.e.
+       If ``true``, include case comparison:
 
        - When used with ``strength:1``, collation compares base characters
          and case.
@@ -176,12 +176,15 @@ parameters and the locales they are associated with, see
      - Optional. Flag that determines whether to compare numeric strings as numbers
        or as strings.
 
-       If ``true``, compare as numbers; i.e. ``"10"`` is greater than
-       ``"2"``.
+       If ``true``, compare as numbers. For example,
+       ``"10"`` is greater than ``"2"``.
 
-       If ``false``, compare as strings; i.e. ``"10"`` is less than ``"2"``.
+       If ``false``, compare as strings. For example,
+       ``"10"`` is less than ``"2"``.
 
        Default is ``false``.
+
+       See :ref:`numericOrdering Restrictions <numeric-order-restrictions>`.
 
 
 
@@ -237,12 +240,12 @@ parameters and the locales they are associated with, see
 
           * - ``"punct"``
 
-            - Both whitespace and punctuation are "ignorable", i.e. not
+            - Both whitespace and punctuation are ignorable and not
               considered base characters.
 
           * - ``"space"``
 
-            - Whitespace are "ignorable", i.e. not considered base
+            - Whitespace is ignorable and not considered to be base
               characters.
 
 
@@ -334,7 +337,98 @@ Collation and Unsupported Index Types
 .. include::  /includes/extracts/collation-index-type-restrictions.rst
 
 .. include:: /includes/extracts/collation-index-type-restrictions-addendum.rst
+
+Restrictions
+------------
+
+.. _numeric-order-restrictions:
+
+numericOrdering
+~~~~~~~~~~~~~~~
+
+When specifying the ``numericOrdering`` as ``true`` the following 
+restrictions apply:
+
+- Only contiguous non-negative integer substrings of digits are 
+  considered in the comparisons. 
+
+  ``numericOrdering`` does not support:
+
+  - ``+``
+  - ``-``
+  - decimal separators, like decimal points and decimal commas
+  - exponents
+
+- Only Unicode code points in the Number or Decimal Digit (Nd) category 
+  are treated as digits.
+
+- If a digit length exceeds 254 characters, the excess characters are 
+  treated as a separate number.
+
+Consider a collection with the following string number and decimal 
+values:
+
+.. code-block:: javascript
+   :emphasize-lines: 6,10
+
+   db.c.insertMany(
+     [
+         { "n" : "1" },
+         { "n" : "2" },
+         { "n" : "2.1" },
+         { "n" : "-2.1" },
+         { "n" : "2.2" },
+         { "n" : "2.10" },
+         { "n" : "2.20" },
+         { "n" : "-10" },
+         { "n" : "10" },
+         { "n" : "20" },
+         { "n" : "20.1" }
+     ]
+   )
+
+The following :method:`find <db.collection.find()>` query uses a 
+collation document containing the ``numericOrdering`` parameter:
+
+.. code-block:: javascript
+
+   db.c.find(
+      { }, { _id: 0 }
+   ).sort(
+     { n: 1 }
+   ).collation( {
+     locale: 'en_US',
+     numericOrdering: true
+   } )
+
+The operation returns the following results:
+
+.. code-block:: javascript
+   :emphasize-lines: 2-3,7-8
+   :copyable: false
 
+   [
+       { n: '-2.1' },
+       { n: '-10' },
+       { n: '1' },
+       { n: '2' },
+       { n: '2.1' },
+       { n: '2.2' },
+       { n: '2.10' },
+       { n: '2.20' },
+       { n: '10' },
+       { n: '20' },
+       { n: '20.1' }
+   ]
+
+- ``numericOrdering: true`` sorts the string values in ascending 
+  order as if they were numeric values.
+- The two negative values ``-2.1`` and ``-10`` are not sorted in the 
+  expected sort order because they have unsupported ``-`` characters.
+- The value ``2.2`` is sorted before the value ``2.10``, due to the fact
+  that the ``numericOrdering`` parameter does not support decimal 
+  values.
+- As a result, ``2.2`` and ``2.10`` are sorted in lexicographic order.
 
 .. toctree::
    :titlesonly: