compareNatural.md (2711B)
1 <!-- Note: This file is automatically generated from source code comments. Changes made in this file will be overridden. --> 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 ### Throws 51 52 Type | Description 53 ---- | ----------- 54 55 56 ## Examples 57 58 ```js 59 math.compareNatural(6, 1) // returns 1 60 math.compareNatural(2, 3) // returns -1 61 math.compareNatural(7, 7) // returns 0 62 63 math.compareNatural('10', '2') // returns 1 64 math.compareText('10', '2') // returns -1 65 math.compare('10', '2') // returns 1 66 67 math.compareNatural('Answer: 10', 'Answer: 2') // returns 1 68 math.compareText('Answer: 10', 'Answer: 2') // returns -1 69 math.compare('Answer: 10', 'Answer: 2') 70 // Error: Cannot convert "Answer: 10" to a number 71 72 const a = math.unit('5 cm') 73 const b = math.unit('40 mm') 74 math.compareNatural(a, b) // returns 1 75 76 const c = math.complex('2 + 3i') 77 const d = math.complex('2 + 4i') 78 math.compareNatural(c, d) // returns -1 79 80 math.compareNatural([1, 2, 4], [1, 2, 3]) // returns 1 81 math.compareNatural([1, 2, 3], [1, 2]) // returns 1 82 math.compareNatural([1, 5], [1, 2, 3]) // returns 1 83 math.compareNatural([1, 2], [1, 2]) // returns 0 84 85 math.compareNatural({a: 2}, {a: 4}) // returns -1 86 ``` 87 88 89 ## See also 90 91 [compare](compare.md), 92 [compareText](compareText.md)