Fixed #1065, #1121: Fixed wrong documentation of function `compareNat…

…ural` and clarified the behavior for strings

HISTORY.md

@@ -1,6 +1,12 @@
 # History
 
 
+## not yet released, version 4.4.2
+
+- Fixed #1065, #1121: Fixed wrong documentation of function
+  `compareNatural` and clarified the behavior for strings.
+
+
 ## 2018-05-29, version 4.4.1
 
 - Fixed #1109: a bug in `inv` when dealing with values close to zero.

lib/function/relational/compareNatural.js

@@ -23,7 +23,11 @@ function factory (type, config, load, typed) {
    * For Complex numbers, first the real parts are compared. If equal,
    * the imaginary parts are compared.
    *
-   * Strings are compared lexically.
+   * Strings are compared with a natural sorting algorithm, which
+   * orders strings in a "logic" way following some heuristics.
+   * This differs from the function `compare`, which converts the string
+   * into a numeric value and compares that. The function `compareText`
+   * on the other hand compares text lexically.
    *
    * Arrays and Matrices are compared value by value until there is an
    * unequal pair of values encountered. Objects are compared by sorted
@@ -40,6 +44,13 @@ function factory (type, config, load, typed) {
    *    math.compareNatural(7, 7);              // returns 0
    *
    *    math.compareNatural('10', '2');         // returns 1
+   *    math.compareText('10', '2');            // returns -1
+   *    math.compare('10', '2');                // returns 1
+   *
+   *    math.compareNatural('Answer: 10', 'Answer: 2'); // returns 1
+   *    math.compareText('Answer: 10', 'Answer: 2');    // returns -1
+   *    math.compare('Answer: 10', 'Answer: 2');
+   *        // Error: Cannot convert "Answer: 10" to a number
    *
    *    var a = math.unit('5 cm');
    *    var b = math.unit('40 mm');