1 |
|
2 |
|
3 | # Function compareNatural
|
4 |
|
5 | Compare two values of any type in a deterministic, natural way.
|
6 |
|
7 | For numeric values, the function works the same as `math.compare`.
|
8 | For types of values that can't be compared mathematically,
|
9 | the function compares in a natural way.
|
10 |
|
11 | For numeric values, x and y are considered equal when the relative
|
12 | difference between x and y is smaller than the configured epsilon.
|
13 | The function cannot be used to compare values smaller than
|
14 | approximately 2.22e-16.
|
15 |
|
16 | For Complex numbers, first the real parts are compared. If equal,
|
17 | the imaginary parts are compared.
|
18 |
|
19 | Strings are compared with a natural sorting algorithm, which
|
20 | orders strings in a "logic" way following some heuristics.
|
21 | This differs from the function `compare`, which converts the string
|
22 | into a numeric value and compares that. The function `compareText`
|
23 | on the other hand compares text lexically.
|
24 |
|
25 | Arrays and Matrices are compared value by value until there is an
|
26 | unequal pair of values encountered. Objects are compared by sorted
|
27 | keys until the keys or their values are unequal.
|
28 |
|
29 |
|
30 | ## Syntax
|
31 |
|
32 | ```js
|
33 | math.compareNatural(x, y)
|
34 | ```
|
35 |
|
36 | ### Parameters
|
37 |
|
38 | Parameter | Type | Description
|
39 | --------- | ---- | -----------
|
40 | `x` | * | First value to compare
|
41 | `y` | * | Second value to compare
|
42 |
|
43 | ### Returns
|
44 |
|
45 | Type | Description
|
46 | ---- | -----------
|
47 | number | Returns the result of the comparison: 1 when x > y, -1 when x < y, and 0 when x == y.
|
48 |
|
49 |
|
50 | ## Examples
|
51 |
|
52 | ```js
|
53 | math.compareNatural(6, 1) // returns 1
|
54 | math.compareNatural(2, 3) // returns -1
|
55 | math.compareNatural(7, 7) // returns 0
|
56 |
|
57 | math.compareNatural('10', '2') // returns 1
|
58 | math.compareText('10', '2') // returns -1
|
59 | math.compare('10', '2') // returns 1
|
60 |
|
61 | math.compareNatural('Answer: 10', 'Answer: 2') // returns 1
|
62 | math.compareText('Answer: 10', 'Answer: 2') // returns -1
|
63 | math.compare('Answer: 10', 'Answer: 2')
|
64 | // Error: Cannot convert "Answer: 10" to a number
|
65 |
|
66 | const a = math.unit('5 cm')
|
67 | const b = math.unit('40 mm')
|
68 | math.compareNatural(a, b) // returns 1
|
69 |
|
70 | const c = math.complex('2 + 3i')
|
71 | const d = math.complex('2 + 4i')
|
72 | math.compareNatural(c, d) // returns -1
|
73 |
|
74 | math.compareNatural([1, 2, 4], [1, 2, 3]) // returns 1
|
75 | math.compareNatural([1, 2, 3], [1, 2]) // returns 1
|
76 | math.compareNatural([1, 5], [1, 2, 3]) // returns 1
|
77 | math.compareNatural([1, 2], [1, 2]) // returns 0
|
78 |
|
79 | math.compareNatural({a: 2}, {a: 4}) // returns -1
|
80 | ```
|
81 |
|
82 |
|
83 | ## See also
|
84 |
|
85 | [compare](compare.md),
|
86 | [compareText](compareText.md)
|
87 |
|
\ | No newline at end of file |