Clarify some of the subtleties linked to term ordering in the docs (#5238)

1 files changed, 9 insertions, 1 deletions

diff --git a/lib/elixir/pages/Operators.md b/lib/elixir/pages/Operators.md
index 4d6fa1ecb..47f2370ae 100644
--- a/lib/elixir/pages/Operators.md
+++ b/lib/elixir/pages/Operators.md
@@ -64,9 +64,17 @@ true
 The reason we can compare different data types is pragmatism. Sorting algorithms don’t need to worry about different data types in order to sort. For reference, the overall sorting order is defined below:
 
 ```
-number < atom < reference < functions < port < pid < tuple < maps < list < bitstring
+number < atom < reference < functions < port < pid < tuple < map < list < bitstring
 ```
 
+When comparing two numbers of different types (a number is either an integer or a float), a conversion to the type with lesser precision will always occur, unless the comparison operator used is either `===` or `!==`. A float will be considered more precise than an integer, unless the float is greater/less than +/-9007199254740992.0, at which point all the significant figures of the float are to the left of the decimal point. This behavior exists so that the comparison of large numbers remains transitive.
+
+The collection types are compared using the following rules:
+
+* Tuples are compared by size then element by element.
+* Maps are compared by size then by keys in ascending term order then by values in key order. In the specific case of maps' key ordering, integers are always considered to be less than floats.
+* Lists are compared element by element.
+
 ## Custom and overridden operators
 
 ### Defining custom operators