Author: lwall Date: 2009-11-27 18:16:22 +0100 (Fri, 27 Nov 2009) New Revision: 29203

Modified: docs/Perl6/Spec/S02-bits.pod docs/Perl6/Spec/S32-setting-library/Numeric.pod Log: [S02] clarify when precision may (not) be lost on Rat calculation [S32/Numeric] add scaling option to round() Modified: docs/Perl6/Spec/S02-bits.pod =================================================================== --- docs/Perl6/Spec/S02-bits.pod 2009-11-27 15:38:38 UTC (rev 29202) +++ docs/Perl6/Spec/S02-bits.pod 2009-11-27 17:16:22 UTC (rev 29203) @@ -677,20 +677,41 @@ However, for pragmatic reasons, C<Rat> values are guaranteed to be exact only up to a certain point. By default, this is the precision that would be represented by the C<Rat64> type, which is an alias for -C<Rational[Int,int64]>, which has a numerator -of C<Int> but is limited to a denominator of C<int64>. A C<Rat64> that +C<Rational[Int,uint64]>, which has a numerator +of C<Int> but is limited to a denominator of C<uint64>. A C<Rat64> that would require more than 64 bits of storage in the denominator is automatically converted either to a C<Num> or to a lesser-precision C<Rat>, at the discretion of the implementation. (Native types such as C<rat64> limit the size of both numerator and denominator, though not to the same size. The numerator should in general be twice the size of the denominator to support user expectations. For instance, -a C<rat8> actually supports C<Rational[int16,int8], allowing +a C<rat8> actually supports C<Rational[int16,uint8], allowing numbers like C<100.01> to be represented, and a C<rat64>, defined as C<Rational[int128,int64]>, can hold the number of seconds since the Big Bang with attosecond precision. Though perhaps not with attosecond accuracy...) +The limitation on C<Rat> values is intended to be enforced only on +user-visible types. Intermediate values used internally in calculation +the values of C<Rat> operators may exceed this precision, or represent +negative denominators. That is, the temporaries used in calculating +the new numerator and denominator are (at least in the abstract) of +C<Int> type. After a new numerator and denominator are determined, +any sign is forced to be represented only by the numerator. Then if +the denominator exceeds the storage size of the unsigned integer used, +the fraction is reduced via gcd. If the resulting denominator is still +larger than the storage size, then and I<only> then may the precision +be reduced to fit into a C<Rat> or C<Num>. + +C<Rat> addition and subtraction should attempt to preserve the +denominator of the more precise argument if that denominator is +an integral multiple of the less precise denominator. That is, +in practical terms, adding a column of dollars and cents should +generally end up with a result that has a denominator of 100, even +if values like 42 and 3.5 were added in. With other operators, +this guarantee cannot be made; in such cases, the user should probably +be explicitly rounding to a particular denominator anyway. + For applications that really need arbitrary precision denominators as well as numerators at the cost of performance, C<FatRat> may be used, which is defined as C<Rational[Int,Int], that is, as arbitrary precision in Modified: docs/Perl6/Spec/S32-setting-library/Numeric.pod =================================================================== --- docs/Perl6/Spec/S32-setting-library/Numeric.pod 2009-11-27 15:38:38 UTC (rev 29202) +++ docs/Perl6/Spec/S32-setting-library/Numeric.pod 2009-11-27 17:16:22 UTC (rev 29203) @@ -19,8 +19,8 @@ Created: 19 Mar 2009 extracted from S29-functions.pod - Last Modified: 1 Sep 2009 - Version: 3 + Last Modified: 27 Nov 2009 + Version: 4 The document is a draft. @@ -182,11 +182,19 @@ =item round - our Int multi method round ( Real $x: ) is export + our Int multi method round ( Real $x: $scale = 1) is export -Returns the nearest integer to C<$x>. The algorithm is C<floor($x + 0.5)>. +Returns the nearest integer to C<$x>. The algorithm is: + + floor($x / $scale + 0.5) * $scale + (Other rounding algorithms will be given extended names beginning with "round".) +Functions that round to a particular precision may easily be created with +currying: + + constant &roundcents ::= &round.assuming(:scale(1/100)); + =item truncate our Int multi method truncate ( Real $x: ) is export