introduce X::Numeric::Real

Signed-off-by: Moritz Lenz <moritz@faui2k3.org>

S32-setting-library/Exception.pod

@@ -1235,6 +1235,20 @@ not know how to handle.
         }
     }
 
+=head2 X::Numeric::Real
+
+Occurs when an attempt to coerce a C<Numeric> to a C<Real>, C<Num>, C<Int> or
+C<Rat> fails (due to a number with a nonzero imaginary part, for instance).
+
+    my class X::Numeric::Real is Exception {
+        has $.target;
+        has $.reason;
+
+        method message() {
+            "Can not convert Numeric to {$.target.^name}: $.reason";
+        }
+    }
+
 =head1 Related types
 
 =head2 Failure

S32-setting-library/Numeric.pod

@@ -85,28 +85,30 @@ mathematical functions.
 
 If this C<Numeric> is equivalent to a C<Real>, return that C<Real>.  
 (For instance, if this number is a C<Complex> with a zero imaginary part.)  
-Fail otherwise.
+Fail with C<X::Numeric::Real> otherwise.
 
 =item Int
 
  multi method Int ( --> Int )
 
 If this C<Numeric> is equivalent to a C<Real>, return the equivalent of
-calling C<truncate> on that C<Real> to get an C<Int>. 
+calling C<truncate> on that C<Real> to get an C<Int>. Fail with
+C<X::Numeric::Real> otherwise.
 
 =item Rat
 
  multi method Rat ( Real $epsilon = 1.0e-6 --> Rat )
 
 If this C<Numeric> is equivalent to a C<Real>, return a C<Rat> which is
-within C<$epsilon> of that C<Real>'s value.
+within C<$epsilon> of that C<Real>'s value. Fail with C<X::Numeric::Real>
+otherwise.
 
 =item Num
 
  multi method Num ( --> Num )
 
 If this C<Numeric> is equivalent to a C<Real>, return that C<Real> as a C<Num>
-as accurately as is possible.
+as accurately as is possible. Fail with C<X::Numeric::Real> otherwise.
 
 =item succ