Revision 28597

Date:
2009/10/04 17:15:53
Author:
moritz
Revision 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
Files:

Legend:

 
Added
 
Removed
 
Modified

  • docs/Perl6/Spec/S32-setting-library/Numeric.pod

     
    28 28 repository under /docs/Perl6/Spec/S32-setting-library/Numeric.pod so edit it there in
    29 29 the SVN repository if you would like to make changes.
    30 30
    31 This documents Bit, Int, Num, Rat, Complex, and Bool.
    31 This documents Bit, Int, Numeric, Rat, Complex, and Bool.
    32 32
    33 33 XXX So where are Bit, Int, and Rat
    34 34
    … …  
    52 52
    53 53 =back
    54 54
    55 =head2 Num
    55 =head2 Numeric
    56 56
    57 The following are all defined in the C<Num> role:
    57 C<Numeric> is a role for everything that's a scalar number. So C<Num>, C<Int>,
    58 C<Rat>, C<Complex> and other numeric types do that role. However it is an
    59 abstract interface, so C<$number.WHAT> will never return C<Numeric>. Users who
    60 provide their own scalar numeric types are encouraged to implement the
    61 C<Numeric> role.
    58 62
    59 B<API document>: L<Num>
    63 The following are all defined in the C<Numeric> role:
    60 64
    61 C<Num> provides some constants in addition to the basic
    65 C<Numeric> provides some constants in addition to the basic
    62 66 mathematical functions.
    63 67
    64 68 constant pi is export = 3.14159_26535_89793_23846_26433_83279_50288;
    … …  
    68 72
    69 73 =item succ
    70 74
    71 our Num multi method succ ( Num $x: ) is export
    72 our Int multi method succ ( Int $x: ) is export
    75 our Numeric multi method succ ( Numeric $x: ) is export
    76 our Int multi method succ ( Int $x: ) is export
    73 77
    74 78 Returns the successor of C<$x>. This method is used by C<< prefix:<++> >> and
    75 79 C<< postfix:<++> >> to increment the value in a container.
    76 80
    77 81 =item pred
    78 82
    79 our Num multi method pred ( Num $x: ) is export
    80 our Int multi method pred ( Int $x: ) is export
    83 our Numeric multi method pred ( Numeric $x: ) is export
    84 our Int multi method pred ( Int $x: ) is export
    81 85
    82 86 Returns the predeccessor of C<$x>. This method is used by C<< prefix:<--> >>
    83 87 and C<< postfix:<--> >> to decrement the value in a container.
    84 88
    85 89 =item abs
    86 90
    87 our Num multi method abs ( Num $x: ) is export
    91 our Numeric multi method abs ( Numeric $x: ) is export
    88 92
    89 93 Absolute Value.
    90 94
    91 =item floor
    92
    93 our Int multi method floor ( Num $x: ) is export
    94
    95 Returns the highest integer not greater than C<$x>.
    96
    97 =item ceiling
    98
    99 our Int multi method ceiling ( Num $x: ) is export
    100
    101 Returns the lowest integer not less than C<$x>.
    102
    103 =item round
    104
    105 our Int multi method round ( Num $x: ) is export
    106
    107 Returns the nearest integer to C<$x>. The algorithm is C<floor($x + 0.5)>.
    108 (Other rounding algorithms will be given extended names beginning with "round".)
    109
    110 =item truncate
    111
    112 our Int multi method truncate ( Num $x: ) is export
    113
    114 Returns the closest integer to C<$x> whose absolute value is not greater
    115 than the absolute value of C<$x>. (In other words, just chuck any
    116 fractional part.) This is the default rounding function used by
    117 implicit integer conversions.
    118
    119 You may also truncate using explicit integer casts, either C<Int()> for
    120 an arbitrarily large integers, or C<int()> for native integers.
    121
    122 95 =item exp
    123 96
    124 our Num multi method exp ( Num $exponent: Num :$base = Num::e ) is export
    97 our Numeric multi method exp ( Numeric $exponent: Numeric :$base = Num::e ) is export
    125 98
    126 99 Performs similar to C<$base ** $exponent>. C<$base> defaults to the
    127 100 constant I<e>.
    128 101
    129 102 =item log
    130 103
    131 our Num multi method log ( Num $x: Num $base = Num::e ) is export
    104 our Numeric multi method log ( Numeric $x: Numeric $base = Num::e ) is export
    132 105
    133 106 Logarithm of base C<$base>, default Natural. Calling with C<$x == 0> is an
    134 107 error.
    135 108
    136 109 =item log10
    137 110
    138 our Num multi method log10 (Num $x:) is export
    111 our Numeric multi method log10 (Numeric $x:) is export
    139 112
    140 113 A base C<10> logarithm, othewise identical to C<log>.
    141 114
    … …  
    148 121 unary C<rand> function in Perl 6, so just multiply C<rand> by your
    149 122 desired multiplier. For picking a random integer you probably want
    150 123 to use something like C<(1..6).pick> instead.
    151
    152 =item sign
    153
    154 our Int multi method sign ( Num $x: ) is export
    155
    156 Returns 1 when C<$x> is greater than 0, -1 when it is less than 0, 0 when it
    157 is equal to 0, or undefined when the value passed is undefined.
    158
    159 =item srand
    160
    161 multi method srand ( Num $seed: )
    162 multi srand ( Num $seed = default_seed_algorithm())
    163
    164 Seed the generator C<rand> uses. C<$seed> defaults to some combination
    165 of various platform dependent characteristics to yield a non-deterministic seed.
    166 Note that you get one C<srand()> for free when you start a Perl program, so
    167 you I<must> call C<srand()> yourself if you wish to specify a deterministic seed
    168 (or if you wish to be differently nondeterministic).
    169
    170 =item sqrt
    171
    172 our Num multi method sqrt ( Num $x: ) is export
    173
    174 Returns the square root of the parameter.
    175
    176 124 =item roots
    177 125
    178 (in Num) method roots (Numeric $x: Int $n --> List of Num) is export
    126 method roots (Numeric $x: Int $n --> List of Num) is export
    179 127
    180 128 Returns a list of all C<$n>th (complex) roots of C<$x>. Returns C<NaN> if
    181 129 C<< $n <= 0 >>, itself if C<$n == 0>, and is free to return a single C<NaN>
    … …  
    184 132
    185 133 =item cis
    186 134
    187 our Complex multi method cis (Num $angle:) is export
    135 our Complex multi method cis (Real $angle:) is export
    188 136
    189 137 Returns 1.unpolar($angle)
    190 138
    191 139 =item unpolar
    192 140
    193 our Complex multi method unpolar (Num $mag: Num $angle) is export
    141 our Complex multi method unpolar (Real $mag: Real $angle) is export
    194 142
    195 143 Returns a complex number specified in polar coordinates. Angle is in radians.
    196 144
    … …  
    208 156 =back
    209 157
    210 158
    159 =head2 Real
    160
    161 role Real does Numeric;
    162
    163 C<Real>, like C<Numeric>, is an abstract role that represents the interface of
    164 a real scalar number (ie neither C<Complex> nor vector-like). For example
    165 C<Num>, C<Int>, C<Bool> and C<Rat> implement the C<Real> role.
    166
    167 =over
    168
    169 =item floor
    170
    171 our Int multi method floor ( Real $x: ) is export
    172
    173 Returns the highest integer not greater than C<$x>.
    174
    175 =item ceiling
    176
    177 our Int multi method ceiling ( Real $x: ) is export
    178
    179 Returns the lowest integer not less than C<$x>.
    180
    181 =item round
    182
    183 our Int multi method round ( Real $x: ) is export
    184
    185 Returns the nearest integer to C<$x>. The algorithm is C<floor($x + 0.5)>.
    186 (Other rounding algorithms will be given extended names beginning with "round".)
    187
    188 =item truncate
    189
    190 our Int multi method truncate ( Real $x: ) is export
    191
    192 Returns the closest integer to C<$x> whose absolute value is not greater
    193 than the absolute value of C<$x>. (In other words, just chuck any
    194 fractional part.) This is the default rounding function used by
    195 implicit integer conversions.
    196
    197 You may also truncate using explicit integer casts, either C<Int()> for
    198 an arbitrarily large integers, or C<int()> for native integers.
    199
    200 =item sign
    201
    202 our Int multi method sign ( Real $x: ) is export
    203
    204 Returns 1 when C<$x> is greater than 0, -1 when it is less than 0, 0 when it
    205 is equal to 0, or undefined when the value passed is undefined.
    206
    207 =item srand
    208
    209 multi method srand ( Real $seed: )
    210 multi srand ( Real $seed = default_seed_algorithm())
    211
    212 Seed the generator C<rand> uses. C<$seed> defaults to some combination
    213 of various platform dependent characteristics to yield a non-deterministic seed.
    214 Note that you get one C<srand()> for free when you start a Perl program, so
    215 you I<must> call C<srand()> yourself if you wish to specify a deterministic seed
    216 (or if you wish to be differently nondeterministic).
    217
    218 =item sqrt
    219
    220 our Real multi method sqrt ( Real $x: ) is export
    221
    222 Returns the square root of the parameter.
    223
    224
    225 =back
    226
    227 =head2 Num
    228
    229 class Num does Real;
    230
    231 C<Num> is a machine-precision numeric real value.
    232
    211 233 =head2 Complex
    212 234
    213 235 C<Complex> is an immutable type. Each C<Complex> object stores two numbers,
    … …  
    222 244
    223 245 =over 4
    224 246
    247 =item new
    248
    249 our Complex multi method new(Real $re, Real $im)
    250
    251 Constructs a C<Complex> number from real and imaginary part. This is the
    252 method form of C<$re + ($im)i>.
    253
    225 254 =item polar
    226 255
    227 256 our Seq multi method polar (Complex $nim:) is export
    … …  
    245 274
    246 275 =head2 Trigonometric functions
    247 276
    248 The following are also defined in C<Num>. The trig functions
    277 The following are also defined in C<Numeric>. The trig functions
    249 278 depend on the current (lexically scoped) trig base:
    250 279
    251 280 enum TrigBase is export <Radians Degrees Gradians Circles>;
    … …  
    255 284
    256 285 =item I<Standard Trig Functions>
    257 286
    258 Num multi method func ( Num $x: TrigBase $base = $?TRIGBASE ) is export
    287 Nuermic multi method func ( Nuermic $x: TrigBase $base = $?TRIGBASE ) is export
    259 288
    260 289 where I<func> is one of:
    261 290 sin, cos, tan, asin, acos, atan, sec, cosec, cotan, asec, acosec,
    … …  
    281 310
    282 311 =item atan2
    283 312
    284 our Num multi method atan2 ( Num $y: Num $x = 1 )
    285 our Num multi atan2 ( Num $y, Num $x = 1 )
    313 our Nuermic multi method atan2 ( Nuermic $y: Nuermic $x = 1 )
    314 our Nuermic multi atan2 ( Nuermic $y, Nuermic $x = 1 )
    286 315
    287 316 This second form of C<atan> computes the arctangent of C<$y/$x>, and takes
    288 317 the quadrant into account. Otherwise behaves as other trigonometric functions.
    289 318
    290 319 =back
    291 320
    321 =head2 Int
    322
    323 An C<Int> is an immutable, integral number of arbitrary size.
    324
    325 =head2 Rat
    326
    327 class Rat does Real;
    328
    329 An immutable rational number, represented by two C<Int>s, a numerator and
    330 a denominator. All interface methods return values as if the numerator and
    331 denominator were stored in a normal form: both numerator and denominator are
    332 minimal in their magnitude, and the denominator is positive. So
    333 C<Rat.new(2, -4).denominator> return C<2>, because the normal form is C<-1/2>.
    334
    335 =over
    336
    337 =item new
    338
    339 multi method new(Int $num, Int $denom)
    340
    341 Constructs a C<Rat> object from the numerator and denominator.
    342 Fails if C<$denom == 0>.
    343
    344 =item nude
    345
    346 our Seq[Int] multi method nude()
    347
    348 Returns a C<Seq> of numerator and denominator
    349
    350 =item denominator
    351
    352 our Int multi method denominator()
    353
    354 Returns the denominator
    355
    356 =item numerator
    357
    358 our Int multi method numerator()
    359
    360 Returns the numerator
    361
    362 =back
    363
    364
    292 365 =head1 Additions
    293 366
    294 367 Please post errors and feedback to perl6-language. If you are making