Author: lwall
Date: 2009-11-17 18:28:47 +0100 (Tue, 17 Nov 2009)
New Revision: 29110

[S02,S09] break the assumption that Rats should be symmetrical
Add Ratio for performance-destroying but truly arbitrary-precision rationals
rename STASH to Stash for consistency

Modified: docs/Perl6/Spec/S02-bits.pod
--- docs/Perl6/Spec/S02-bits.pod        2009-11-17 16:09:39 UTC (rev 29109)
+++ docs/Perl6/Spec/S02-bits.pod        2009-11-17 17:28:47 UTC (rev 29110)
@@ -13,8 +13,8 @@
     Created: 10 Aug 2004
-    Last Modified: 09 Nov 2009
-    Version: 187
+    Last Modified: 17 Nov 2009
+    Version: 188
 This document summarizes Apocalypse 2, which covers small-scale
 lexical items and typological issues.  (These Synopses also contain
@@ -674,13 +674,23 @@
 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 a C<rat64> type, that is, with a numerator
-and denominator consisting of C<int64> values.  C<Rat>s that would require
-more than 64 bits of storage in either numerator or denominator are
-automatically converted to C<Num>s.  (If rationals are defined by a
-role, it may be possible to instantiate a C<Rat> type with a different
-maximum precision.)
+that would be represented by the C<Rat64> type, which has a numerator
+of C<Int> but is limited to a denominator of C<int64>.  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> should actually support C<int16/int8>, allowing
+numbers like C<100.01> to be represented, and a C<rat64>,
+defined as C<int128/int64>, can hold the number of seconds since
+the Big Bang with picosecond precision.  Though perhaps not with
+picosecond accuracy...)
+For applications that really need arbitrary precision denominators
+as well as numerators, C<Ratio> may be used, which is defined as C<Int/Int>.
 =item *
 PerlĀ 6 should by default make standard IEEE floating point concepts
@@ -959,6 +969,7 @@
     int         native signed integer
     uint        native unsigned integer (autoboxes to Int)
     buf         native buffer (finite seq of native ints or uints, no Unicode)
+    rat         native rational
     num         native floating point
     complex     native complex number
     bool        native boolean
@@ -1073,8 +1084,9 @@
     Str         Perl string (finite sequence of Unicode characters)
     Bit         Perl single bit (allows traits, aliasing, undef, etc.)
     Int         Perl integer (allows Inf/NaN, arbitrary precision, etc.)
-    Num         Perl number (approximate Real)
-    Rat         Perl rational (exact Real)
+    Num         Perl number (approximate Real, generally via floating point)
+    Rat         Perl rational (exact Real, limited denominator)
+    Ratio       Perl rational (unlimited precision in both parts)
     Complex     Perl complex number
     Bool        Perl boolean
     Exception   Perl exception
@@ -1115,7 +1127,8 @@
 native TAI value.  In numeric context a C<Duration> happily returns a
 C<Num> representing seconds.  If pressed for a number, an C<Instant>
 will return the length of time in atomic seconds from the TAI epoch,
-but it will be unhappy about it.  Systems which cannot provide
+but it will be unhappy about it.  (The time will be returned as a C<Rat>
+to preserve maximal precision and accuracy.)  Systems which cannot provide
 a steady time base, such as POSIX systems, will simply have to make
 their best guess as to the correct atomic time.
@@ -1128,6 +1141,7 @@
     Int         Numeric Integral
     Num         Numeric Real
     Rat         Numeric Real
+    Ratio       Numeric Real
     Complex     Numeric
     Bool        Boolean
     Exception   Failure
@@ -1169,7 +1183,7 @@
     Macro       Perl compile-time subroutine
     Regex       Perl pattern
     Match       Perl match, usually produced by applying a pattern
-    STASH       A symbol table hash (package, module, class, lexpad, etc)
+    Stash       A symbol table hash (package, module, class, lexpad, etc)
     SoftRoutine A routine that is committed to staying mutable
 The C<KeyHash> role differs from a normal C<Associative> hash in how it 
handles default
@@ -1231,7 +1245,7 @@
     Macro       Callable
     Regex       Callable
     Match       Positional Associative
-    STASH       Associative
+    Stash       Associative
     SoftRoutine Routine
 See L<S06/"Wrapping"> for a discussion of soft vs. hard routines.

Modified: docs/Perl6/Spec/S09-data.pod
--- docs/Perl6/Spec/S09-data.pod        2009-11-17 16:09:39 UTC (rev 29109)
+++ docs/Perl6/Spec/S09-data.pod        2009-11-17 17:28:47 UTC (rev 29110)
@@ -13,8 +13,8 @@
     Created: 13 Sep 2004
-    Last Modified: 21 Sep 2009
-    Version: 35
+    Last Modified: 17 Nov 2009
+    Version: 36
 =head1 Overview
@@ -81,6 +81,9 @@
 run-time system (presumably Parrot) is compiled in.  So C<int>
 typically means C<int32> or C<int64>, while C<num> usually means
 C<num64>, and C<complex> means two of whatever C<num> turns out to be.
+For symmetry around the decimal point, native rats have a numerator
+that is twice the size of their denominator, such that a rat32 actually
+has an int64 for its numerator.
 You are, of course, free to use macros or type declarations to
 associate additional names, such as "short" or "single".  These are

Reply via email to