Updated some docs

HISTORY.md

@@ -19,8 +19,10 @@ Breaking changes:
 - Changed the behavior of relational functions (`compare`, `equal`,
   `equalScalar`, `larger`, `largerEq`, `smaller`, `smallerEq`, `unequal`)
   to compare strings by their numeric value they contain instead of
-  alphabetically. This also impacts functions `sort`, `min`, `max`,
-  `median`, and `partitionSelect`. See #680.
+  alphabetically. This also impacts functions `deepEqual`, `sort`, `min`,
+  `max`, `median`, and `partitionSelect`. Use `compareNatural` if you
+  need to sort an array with text. See #680.
+
 
 ## 2018-01-17, version 3.20.1
 

lib/function/matrix/sort.js

@@ -21,12 +21,14 @@ function factory (type, config, load, typed) {
    * Examples:
    *
    *    math.sort([5, 10, 1]); // returns [1, 5, 10]
-   *    math.sort(['C', 'B', 'A', 'D']); // returns ['A', 'B', 'C', 'D']
+   *    math.sort(['C', 'B', 'A', 'D'], math.compareNatural);
+   *    // returns ['A', 'B', 'C', 'D']
    *
    *    function sortByLength (a, b) {
    *      return a.length - b.length;
    *    }
-   *    math.sort(['Langdon', 'Tom', 'Sara'], sortByLength); // returns ['Tom', 'Sara', 'Langdon']
+   *    math.sort(['Langdon', 'Tom', 'Sara'], sortByLength);
+   *    // returns ['Tom', 'Sara', 'Langdon']
    *
    * See also:
    *

lib/function/relational/compare.js

@@ -21,6 +21,7 @@ function factory (type, config, load, typed) {
    * compare values smaller than approximately 2.22e-16.
    *
    * For matrices, the function is evaluated element wise.
+   * Strings are compared by their numerical value.
    *
    * Syntax:
    *
@@ -31,6 +32,7 @@ function factory (type, config, load, typed) {
    *    math.compare(6, 1);           // returns 1
    *    math.compare(2, 3);           // returns -1
    *    math.compare(7, 7);           // returns 0
+   *    math.compare('10', '2');      // returns 1
    *
    *    var a = math.unit('5 cm');
    *    var b = math.unit('40 mm');

lib/function/relational/compareNatural.js

@@ -23,6 +23,8 @@ 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.
+   *
    * Arrays and Matrices are compared value by value until there is an
    * unequal pair of values encountered. Objects are compared by sorted
    * keys until the keys or their values are unequal.

lib/function/relational/deepEqual.js

@@ -7,6 +7,8 @@ function factory (type, config, load, typed) {
    * Test element wise whether two matrices are equal.
    * The function accepts both matrices and scalar values.
    *
+   * Strings are compared by their numerical value.
+   *
    * Syntax:
    *
    *    math.deepEqual(x, y)

lib/function/relational/equal.js

@@ -25,7 +25,7 @@ function factory (type, config, load, typed) {
    *
    * Values `null` and `undefined` are compared strictly, thus `null` is only
    * equal to `null` and nothing else, and `undefined` is only equal to
-   * `undefined` and nothing else.
+   * `undefined` and nothing else. Strings are compared by their numerical value.
    *
    * Syntax:
    *
@@ -46,6 +46,7 @@ function factory (type, config, load, typed) {
    *    math.equal(c, d);             // returns [true, false, true]
    *    math.deepEqual(c, d);         // returns false
    *
+   *    math.equal("1000", "1e3");    // returns true
    *    math.equal(0, null);          // returns false
    *
    * See also:

lib/function/relational/larger.js

@@ -23,6 +23,7 @@ function factory (type, config, load, typed) {
    * function cannot be used to compare values smaller than approximately 2.22e-16.
    *
    * For matrices, the function is evaluated element wise.
+   * Strings are compared by their numerical value.
    *
    * Syntax:
    *

lib/function/relational/largerEq.js

@@ -23,6 +23,7 @@ function factory (type, config, load, typed) {
    * function cannot be used to compare values smaller than approximately 2.22e-16.
    *
    * For matrices, the function is evaluated element wise.
+   * Strings are compared by their numerical value.
    *
    * Syntax:
    *

lib/function/relational/smaller.js

@@ -23,6 +23,7 @@ function factory (type, config, load, typed) {
    * function cannot be used to compare values smaller than approximately 2.22e-16.
    *
    * For matrices, the function is evaluated element wise.
+   * Strings are compared by their numerical value.
    *
    * Syntax:
    *

lib/function/relational/smallerEq.js

@@ -21,7 +21,9 @@ function factory (type, config, load, typed) {
    * The function returns true when x is smaller than y or the relative
    * difference between x and y is smaller than the configured epsilon. The
    * function cannot be used to compare values smaller than approximately 2.22e-16.
+   *
    * For matrices, the function is evaluated element wise.
+   * Strings are compared by their numerical value.
    *
    * Syntax:
    *

lib/function/relational/unequal.js

@@ -24,6 +24,7 @@ function factory (type, config, load, typed) {
    *
    * For matrices, the function is evaluated element wise.
    * In case of complex numbers, x.re must unequal y.re, or x.im must unequal y.im.
+   * Strings are compared by their numerical value.
    *
    * Values `null` and `undefined` are compared strictly, thus `null` is unequal
    * with everything except `null`, and `undefined` is unequal with everying

test/function/relational/deepEqual.test.js

@@ -14,6 +14,8 @@ describe('deepEqual', function() {
     assert.equal(deepEqual(2, 2), true);
     assert.equal(deepEqual(0, 0), true);
     assert.equal(deepEqual(-2, 2), false);
+    assert.equal(deepEqual(2, math.bignumber(2)), true);
+    assert.equal(deepEqual(math.fraction(1, 2), 0.5), true);
     assert.equal(deepEqual(true, 1), true);
   });
 
@@ -40,7 +42,8 @@ describe('deepEqual', function() {
   });
 
   it('should compare two matrices with mixed types', function() {
-    assert.deepEqual(deepEqual([1,4,5], [true,4,5]), true);
+    assert.deepEqual(deepEqual([1,4], [true,4]), true);
+    assert.deepEqual(deepEqual([1,4], [1,'4']), true);
     assert.deepEqual(deepEqual([2,3], [2, bignumber(3)]), true);
     assert.deepEqual(deepEqual([2,3], [2, bignumber(4)]), false);
     assert.deepEqual(deepEqual([complex(2,3),3], [complex(2,3),3]), true);
@@ -52,6 +55,10 @@ describe('deepEqual', function() {
     assert.throws(function () {deepEqual(1, 2, 3)}, /TypeError: Too many arguments/);
   });
 
+  it('should throw an error in case of invalid type of arguments', function() {
+    assert.throws(function () {deepEqual(['A'], ['B'])}, /Error: Cannot convert "A" to a number/);
+  });
+
   it('should LaTeX deepEqual', function () {
     var expression = math.parse('deepEqual([1,2],[1,3])');
     assert.equal(expression.toTex(), '\\mathrm{deepEqual}\\left(\\begin{bmatrix}1\\\\2\\\\\\end{bmatrix},\\begin{bmatrix}1\\\\3\\\\\\end{bmatrix}\\right)');