minor #9671 [Finder] Described "use natural sort" option (vyshkant, javiereguiluz)

javiereguiluz · javiereguiluz · commit eee653fa3a01 · 2018-06-01T10:43:53.000+02:00
This PR was merged into the master branch. Discussion ---------- [Finder] Described "use natural sort" option Added description for new `$useNaturalSort` option of `Finder::sortByName()` method. Commits ------- 9649800 Expanded the explanation a bit 0d38d1b [Finder] Described "use natural sort" option
diff --git a/components/finder.rst b/components/finder.rst
@@ -168,17 +168,27 @@ Sort the result by name or by type (directories first, then files)::
 
     $finder->sortByType();
 
-.. note::
+.. tip::
 
-    Notice that the ``sort*`` methods need to get all matching elements to do
-    their jobs. For large iterators, it is slow.
+    By default, the ``sortByName()`` method uses the :phpfunction:`strcmp` PHP
+    function (e.g. ``file1.txt``, ``file10.txt``, ``file2.txt``). Pass ``true``
+    as its argument to use PHP's `natural sort order`_ algorithm instead (e.g.
+    ``file1.txt``, ``file2.txt``, ``file10.txt``).
+
+    .. versionadded:: 4.2
+        The option to use the natural sort order was introduced in Symfony 4.2.
 
 You can also define your own sorting algorithm with ``sort()`` method::
 
     $finder->sort(function (\SplFileInfo $a, \SplFileInfo $b) {
         return strcmp($a->getRealPath(), $b->getRealPath());
     });
 
+.. note::
+
+    Notice that the ``sort*`` methods need to get all matching elements to do
+    their jobs. For large iterators, it is slow.
+
 File Name
 ~~~~~~~~~
 
@@ -320,8 +330,9 @@ The contents of returned files can be read with
         // ...
     }
 
-.. _strtotime:    https://php.net/manual/en/datetime.formats.php
-.. _protocol:     https://php.net/manual/en/wrappers.php
-.. _Streams:      https://php.net/streams
-.. _IEC standard: https://physics.nist.gov/cuu/Units/binary.html
-.. _Packagist:    https://packagist.org/packages/symfony/finder
+.. _strtotime:          https://php.net/manual/en/datetime.formats.php
+.. _protocol:           https://php.net/manual/en/wrappers.php
+.. _Streams:            https://php.net/streams
+.. _IEC standard:       https://physics.nist.gov/cuu/Units/binary.html
+.. _Packagist:          https://packagist.org/packages/symfony/finder
+.. _`natural sort order`: https://en.wikipedia.org/wiki/Natural_sort_order
