Merge pull request #604 from MasterDuke17/add_docs_for_≅

Add some documentation for the =~=/≅ operator

Author: jonathanstowe

doc/Language/operators.pod

@@ -29,7 +29,7 @@ tightest to loosest:
     X  Junctive or       | ^
     L  Named unary       temp let
     N  Structural infix  but does <=> leg cmp .. ..^ ^.. ^..^
-    C  Chaining infix    != == < <= > >= eq ne lt le gt ge ~~ === eqv !eqv
+    C  Chaining infix    != == < <= > >= eq ne lt le gt ge ~~ === eqv !eqv =~=
     X  Tight and         &&
     X  Tight or          || ^^ // min max
     R  Conditional       ?? !! ff fff
@@ -1392,6 +1392,45 @@ Here is an excerpt of built-in smart-matching functionality:
 
 =end table
 
+=head2 infix C«=~=»
+
+    proto sub infix:<=~=>($, $) returns Bool:D is assoc:<chain>
+    multi sub infix:<=~=>(Any, Any)
+    multi sub infix:<=~=>(Int:D, Int:D)
+    multi sub infix:<=~=>(Num:D, Num:D)
+    multi sub infix:<=~=>(Rational:D, Rational:D)
+    multi sub infix:<=~=>(Real:D, Real:D)
+    multi sub infix:<=~=>(Complex:D, Complex:D)
+    multi sub infix:<=~=>(Numeric:D, Numeric:D)
+
+The X<approximately-equal operator>. Calculates the relative difference between
+the left-hand and right-hand sides and returns C<True> if the difference is
+less than $*TOLERANCE (which defaults to 1e-15). However, if either side is zero
+then it checks that the absolute difference between the sides is less than $*TOLERANCE.
+Note that this operator is not arithmetically symetrical (doesn't do ± Δ):
+
+    say ($x + $*TOLERANCE) =~= $x;   # True
+    say ($x - $*TOLERANCE) =~= $x;   # False
+
+The tolerance is supposed to be modifiable via an adverb:
+
+    say $x =~= $y :tolerance(.1);
+
+however, this is not yet implemented. The same effect can be achieved by
+assigning to $*TOLERANCE.
+
+    {
+        my $*TOLERANCE = .1;
+        say 11 =~= 10;               # True
+    }
+
+Note that setting $*TOLERANCE = 0 will cause all comparisons to fail.
+
+    {
+        my $*TOLERANCE = 0;
+        say 1 =~= 1;                 # False
+    }
+
 =head1 Tight AND Precedence
 
 =head2 infix C«&&»