Author: moritz Date: 2009-10-04 19:15:53 +0200 (Sun, 04 Oct 2009) New Revision: 28597

Modified: docs/Perl6/Spec/S32-setting-library/Numeric.pod Log: [S32/Numeric] major overhaul * Most methods that were in Num are now Numeric * sign() and the rounding methods are now in Real * document (at least partially) Rat, Num and Int Modified: docs/Perl6/Spec/S32-setting-library/Numeric.pod =================================================================== --- docs/Perl6/Spec/S32-setting-library/Numeric.pod 2009-10-04 17:15:43 UTC (rev 28596) +++ docs/Perl6/Spec/S32-setting-library/Numeric.pod 2009-10-04 17:15:53 UTC (rev 28597) @@ -28,7 +28,7 @@ repository under /docs/Perl6/Spec/S32-setting-library/Numeric.pod so edit it there in the SVN repository if you would like to make changes. -This documents Bit, Int, Num, Rat, Complex, and Bool. +This documents Bit, Int, Numeric, Rat, Complex, and Bool. XXX So where are Bit, Int, and Rat @@ -52,13 +52,17 @@ =back -=head2 Num +=head2 Numeric -The following are all defined in the C<Num> role: +C<Numeric> is a role for everything that's a scalar number. So C<Num>, C<Int>, +C<Rat>, C<Complex> and other numeric types do that role. However it is an +abstract interface, so C<$number.WHAT> will never return C<Numeric>. Users who +provide their own scalar numeric types are encouraged to implement the +C<Numeric> role. -B<API document>: L<Num> +The following are all defined in the C<Numeric> role: -C<Num> provides some constants in addition to the basic +C<Numeric> provides some constants in addition to the basic mathematical functions. constant pi is export = 3.14159_26535_89793_23846_26433_83279_50288; @@ -68,74 +72,43 @@ =item succ - our Num multi method succ ( Num $x: ) is export - our Int multi method succ ( Int $x: ) is export + our Numeric multi method succ ( Numeric $x: ) is export + our Int multi method succ ( Int $x: ) is export Returns the successor of C<$x>. This method is used by C<< prefix:<++> >> and C<< postfix:<++> >> to increment the value in a container. =item pred - our Num multi method pred ( Num $x: ) is export - our Int multi method pred ( Int $x: ) is export + our Numeric multi method pred ( Numeric $x: ) is export + our Int multi method pred ( Int $x: ) is export Returns the predeccessor of C<$x>. This method is used by C<< prefix:<--> >> and C<< postfix:<--> >> to decrement the value in a container. =item abs - our Num multi method abs ( Num $x: ) is export + our Numeric multi method abs ( Numeric $x: ) is export Absolute Value. -=item floor - - our Int multi method floor ( Num $x: ) is export - -Returns the highest integer not greater than C<$x>. - -=item ceiling - - our Int multi method ceiling ( Num $x: ) is export - -Returns the lowest integer not less than C<$x>. - -=item round - - our Int multi method round ( Num $x: ) is export - -Returns the nearest integer to C<$x>. The algorithm is C<floor($x + 0.5)>. -(Other rounding algorithms will be given extended names beginning with "round".) - -=item truncate - - our Int multi method truncate ( Num $x: ) is export - -Returns the closest integer to C<$x> whose absolute value is not greater -than the absolute value of C<$x>. (In other words, just chuck any -fractional part.) This is the default rounding function used by -implicit integer conversions. - -You may also truncate using explicit integer casts, either C<Int()> for -an arbitrarily large integers, or C<int()> for native integers. - =item exp - our Num multi method exp ( Num $exponent: Num :$base = Num::e ) is export + our Numeric multi method exp ( Numeric $exponent: Numeric :$base = Num::e ) is export Performs similar to C<$base ** $exponent>. C<$base> defaults to the constant I<e>. =item log - our Num multi method log ( Num $x: Num $base = Num::e ) is export + our Numeric multi method log ( Numeric $x: Numeric $base = Num::e ) is export Logarithm of base C<$base>, default Natural. Calling with C<$x == 0> is an error. =item log10 - our Num multi method log10 (Num $x:) is export + our Numeric multi method log10 (Numeric $x:) is export A base C<10> logarithm, othewise identical to C<log>. @@ -148,34 +121,9 @@ unary C<rand> function in PerlĀ 6, so just multiply C<rand> by your desired multiplier. For picking a random integer you probably want to use something like C<(1..6).pick> instead. - -=item sign - - our Int multi method sign ( Num $x: ) is export - -Returns 1 when C<$x> is greater than 0, -1 when it is less than 0, 0 when it -is equal to 0, or undefined when the value passed is undefined. - -=item srand - - multi method srand ( Num $seed: ) - multi srand ( Num $seed = default_seed_algorithm()) - -Seed the generator C<rand> uses. C<$seed> defaults to some combination -of various platform dependent characteristics to yield a non-deterministic seed. -Note that you get one C<srand()> for free when you start a Perl program, so -you I<must> call C<srand()> yourself if you wish to specify a deterministic seed -(or if you wish to be differently nondeterministic). - -=item sqrt - - our Num multi method sqrt ( Num $x: ) is export - -Returns the square root of the parameter. - =item roots - (in Num) method roots (Numeric $x: Int $n --> List of Num) is export + method roots (Numeric $x: Int $n --> List of Num) is export Returns a list of all C<$n>th (complex) roots of C<$x>. Returns C<NaN> if C<< $n <= 0 >>, itself if C<$n == 0>, and is free to return a single C<NaN> @@ -184,13 +132,13 @@ =item cis - our Complex multi method cis (Num $angle:) is export + our Complex multi method cis (Real $angle:) is export Returns 1.unpolar($angle) =item unpolar - our Complex multi method unpolar (Num $mag: Num $angle) is export + our Complex multi method unpolar (Real $mag: Real $angle) is export Returns a complex number specified in polar coordinates. Angle is in radians. @@ -208,6 +156,80 @@ =back +=head2 Real + + role Real does Numeric; + +C<Real>, like C<Numeric>, is an abstract role that represents the interface of +a real scalar number (ie neither C<Complex> nor vector-like). For example +C<Num>, C<Int>, C<Bool> and C<Rat> implement the C<Real> role. + +=over + +=item floor + + our Int multi method floor ( Real $x: ) is export + +Returns the highest integer not greater than C<$x>. + +=item ceiling + + our Int multi method ceiling ( Real $x: ) is export + +Returns the lowest integer not less than C<$x>. + +=item round + + our Int multi method round ( Real $x: ) is export + +Returns the nearest integer to C<$x>. The algorithm is C<floor($x + 0.5)>. +(Other rounding algorithms will be given extended names beginning with "round".) + +=item truncate + + our Int multi method truncate ( Real $x: ) is export + +Returns the closest integer to C<$x> whose absolute value is not greater +than the absolute value of C<$x>. (In other words, just chuck any +fractional part.) This is the default rounding function used by +implicit integer conversions. + +You may also truncate using explicit integer casts, either C<Int()> for +an arbitrarily large integers, or C<int()> for native integers. + +=item sign + + our Int multi method sign ( Real $x: ) is export + +Returns 1 when C<$x> is greater than 0, -1 when it is less than 0, 0 when it +is equal to 0, or undefined when the value passed is undefined. + +=item srand + + multi method srand ( Real $seed: ) + multi srand ( Real $seed = default_seed_algorithm()) + +Seed the generator C<rand> uses. C<$seed> defaults to some combination +of various platform dependent characteristics to yield a non-deterministic seed. +Note that you get one C<srand()> for free when you start a Perl program, so +you I<must> call C<srand()> yourself if you wish to specify a deterministic seed +(or if you wish to be differently nondeterministic). + +=item sqrt + + our Real multi method sqrt ( Real $x: ) is export + +Returns the square root of the parameter. + + +=back + +=head2 Num + + class Num does Real; + +C<Num> is a machine-precision numeric real value. + =head2 Complex C<Complex> is an immutable type. Each C<Complex> object stores two numbers, @@ -222,6 +244,13 @@ =over 4 +=item new + + our Complex multi method new(Real $re, Real $im) + +Constructs a C<Complex> number from real and imaginary part. This is the +method form of C<$re + ($im)i>. + =item polar our Seq multi method polar (Complex $nim:) is export @@ -245,7 +274,7 @@ =head2 Trigonometric functions -The following are also defined in C<Num>. The trig functions +The following are also defined in C<Numeric>. The trig functions depend on the current (lexically scoped) trig base: enum TrigBase is export <Radians Degrees Gradians Circles>; @@ -255,7 +284,7 @@ =item I<Standard Trig Functions> - Num multi method func ( Num $x: TrigBase $base = $?TRIGBASE ) is export + Nuermic multi method func ( Nuermic $x: TrigBase $base = $?TRIGBASE ) is export where I<func> is one of: sin, cos, tan, asin, acos, atan, sec, cosec, cotan, asec, acosec, @@ -281,14 +310,58 @@ =item atan2 - our Num multi method atan2 ( Num $y: Num $x = 1 ) - our Num multi atan2 ( Num $y, Num $x = 1 ) + our Nuermic multi method atan2 ( Nuermic $y: Nuermic $x = 1 ) + our Nuermic multi atan2 ( Nuermic $y, Nuermic $x = 1 ) This second form of C<atan> computes the arctangent of C<$y/$x>, and takes the quadrant into account. Otherwise behaves as other trigonometric functions. =back +=head2 Int + +An C<Int> is an immutable, integral number of arbitrary size. + +=head2 Rat + + class Rat does Real; + +An immutable rational number, represented by two C<Int>s, a numerator and +a denominator. All interface methods return values as if the numerator and +denominator were stored in a normal form: both numerator and denominator are +minimal in their magnitude, and the denominator is positive. So +C<Rat.new(2, -4).denominator> return C<2>, because the normal form is C<-1/2>. + +=over + +=item new + + multi method new(Int $num, Int $denom) + +Constructs a C<Rat> object from the numerator and denominator. +Fails if C<$denom == 0>. + +=item nude + + our Seq[Int] multi method nude() + +Returns a C<Seq> of numerator and denominator + +=item denominator + + our Int multi method denominator() + +Returns the denominator + +=item numerator + + our Int multi method numerator() + +Returns the numerator + +=back + + =head1 Additions Please post errors and feedback to perl6-language. If you are making