Author: lwall
Date: 20090829 21:06:40 +0200 (Sat, 29 Aug 2009)
New Revision: 28113
Modified:
docs/Perl6/Spec/S03operators.pod
Log:
[S03] some tidying of /, %, div, and mod
Modified: docs/Perl6/Spec/S03operators.pod
===================================================================
 docs/Perl6/Spec/S03operators.pod 20090829 18:30:05 UTC (rev 28112)
+++ docs/Perl6/Spec/S03operators.pod 20090829 19:06:40 UTC (rev 28113)
@@ 14,8 +14,8 @@
Created: 8 Mar 2004
 Last Modified: 10 Jul 2009
 Version: 169
+ Last Modified: 29 Aug 2009
+ Version: 170
=head1 Overview
@@ 699,7 +699,16 @@
$numerator / $denominator
If either operand is of C<Num> type, converts both operands to C<Num>
+Performs division of real or complex numbers, returning a real or complex
+number of appropriate type.
+
+If both operands are of integer type, the operator returns the
+corresponding C<Rat> value.
+
+Otherwise, if either operand is of C<Complex> type, converts both
+operands to C<Complex> and does division returning C<Complex>.
+
+Otherwise, if either operand is of C<Num> type, converts both operands to C<Num>
and does division returning C<Num>. If the denominator is zero,
returns an object representing either C<+Inf>, C<NaN>, or C<Inf>
as the numerator is positive, zero, or negative. (This is construed
@@ 711,19 +720,17 @@
in a nonparallel computation, it will likely throw an exception at
that point.)
If both operands are of integer type, you still get a C<Num>, but the
C<Num> type is allowed to do the division lazily; internally it may
store a C<Rat> until the time a value is called for. If converted
to C<Rat> directly no division ever need be done.

=item *
C<< infix:<div> >>, generic division
$numerator div $denominator
Dispatches to the C<< infix:<div> >> multi most appropriate to the operand
types. Policy on what to do about division by zero is up to the type,
+Dispatches to the C<< infix:<div> >> multi most appropriate to the
+operand types, typically returning a value of the same type.
+Not coercive, so fails on differing types.
+
+Policy on what to do about division by zero is up to the type,
but for the sake of hyperoperators and junctions those types that
can represent overflow (or that can contain an unthrown exception)
should try to do so rather than simply throwing an exception. (And in
@@ 731,24 +738,40 @@
use in hyperops and junctions, and whether they can profitably benefit
from a lazy exception model.)
Use of C<div> on two C<Int> values results in a ratio of the C<Rat> type.
+Use of C<div> on builtin integer types is equivalent to taking the
+floor of a real division:
+ $x div $y == floor($x/$y);
+
=item *
C<< infix:<%> >>, modulus
$x % $mod
Always floor semantics using C<Num> or C<Int>.
+Coerces to C<Num> (or C<Int> as an optimization) before performing C<mod>.
+That is, has results equivalent to:
+ floor( Num($x) / Num($y) )
+
+Also preserves the identity:
+
+ $x % $y == $x  floor($x / $y) * $y
+
=item *
C<< infix:<mod> >>, generic modulus
$x mod $mod
Dispatches to the C<< infix:<mod> >> multi most appropriate to the operand types.
+Dispatches to the C<< infix:<mod> >> multi most appropriate to
+the operand types, typically returning a value of the same type.
+Not coercive, so fails on differing types.
+For builtin types, preserves the identity
+
+ $x mod $y == $x  ($x div $y) * $y
+
=item *
C<< infix:{'+&'} >>, numeric bitwise and