DRAFT: Synopsis 32: Setting Library - Numeric
Rod Adams <rod@rodadams.net>
Larry Wall <larry@wall.org>
Aaron Sherman <ajs@ajs.com>
Mark Stosberg <mark@summersault.com>
Carl Mäsak <cmasak@gmail.com>
Moritz Lenz <moritz@faui2k3.org>
Tim Nelson <wayland@wayland.id.au>
Created: 19 Mar 2009 extracted from S29-functions.pod
Last Modified: 27 Nov 2009
Version: 4
The document is a draft.
If you read the HTML version, it is generated from the Pod in the pugs 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, Numeric, Rat, Complex, and Bool.
XXX So where are Bit, Int, and Rat
our Bool multi method succ ( Bool $b: ) is export
Returns Bool::True.
our Bool multi method pred ( Bool $b: ) is export
Returns Bool::False.
Numeric is a role for everything that's a scalar number. So Num, Int, Rat, Complex and other numeric types do that role. However it is an abstract interface, so $number.WHAT will never return Numeric. Users who provide their own scalar numeric types are encouraged to implement the Numeric role.
The following are all defined in the Numeric role:
Numeric provides some constants in addition to the basic mathematical functions.
constant pi is export = 3.14159_26535_89793_23846_26433_83279_50288;
constant e is export = 2.71828_18284_59045_23536_02874_71352_66249;
constant i is export = 1i;
our Numeric multi method succ ( Numeric $x: ) is export our Int multi method succ ( Int $x: ) is export
Returns the successor of $x. This method is used by prefix:<++> and postfix:<++> to increment the value in a container.
our Numeric multi method pred ( Numeric $x: ) is export our Int multi method pred ( Int $x: ) is export
Returns the predecessor of $x. This method is used by prefix:<--> and postfix:<--> to decrement the value in a container.
our Numeric multi method abs ( Numeric $x: ) is export
Absolute Value.
our Numeric multi method exp ( Numeric $exponent: Numeric :$base = Num::e ) is export
Performs similar to $base ** $exponent. $base defaults to the constant e.
our Numeric multi method log ( Numeric $x: Numeric $base = Num::e ) is export
Logarithm of base $base, default Natural. Calling with $x == 0 is an error.
our Numeric multi method log10 (Numeric $x:) is export
A base 10 logarithm, otherwise identical to log.
our Num term:<rand>
Pseudo random number in range 0 ..^ 1. That is, 0 is theoretically possible, while 1 is not. Note that there is no unary rand function in Perl 6, so just multiply rand by your desired multiplier. For picking a random integer you probably want to use something like (1..6).pick instead.
method roots (Numeric $x: Int $n --> List of Num) is export
Returns a list of all $nth (complex) roots of $x. Returns NaN if $n <= 0, itself if $n == 0, and is free to return a single NaN if $x is NaN or Inf, or in case of complex numbers if one of the components is.
our Complex multi method cis (Real $angle:) is export
Returns 1.unpolar($angle)
our Complex multi method unpolar (Real $mag: Real $angle) is export
Returns a complex number specified in polar coordinates. Angle is in radians.
our Complex multi postfix:<i> ( Numeric $x )
Returns a complex number representing the parameter multiplied by the imaginary unit i. Note that there is no .i method. To follow a variable name with the postfix, it's necessary to use a backslash or parentheses:
$land\i
($land)i
role Real does Numeric;
Real, like Numeric, is an abstract role that represents the interface of a real scalar number (i.e. neither Complex nor vector-like). For example Num, Int, Bool and Rat implement the Real role.
our Int multi method floor ( Real $x: ) is export
Returns the highest integer not greater than $x.
our Int multi method ceiling ( Real $x: ) is export
Returns the lowest integer not less than $x.
our Int multi method round ( Real $x: $scale = 1) is export
Returns the nearest integer to $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));
our Int multi method truncate ( Real $x: ) is export
Returns the closest integer to $x whose absolute value is not greater than the absolute value of $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 Int() for an arbitrarily large integers, or int() for native integers.
our Int multi method sign ( Real $x: ) is export
Returns 1 when $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.
multi method srand ( Real $seed: ) multi srand ( Real $seed = default_seed_algorithm())
Seed the generator rand uses. $seed defaults to some combination of various platform dependent characteristics to yield a non-deterministic seed. Note that you get one srand() for free when you start a Perl program, so you must call srand() yourself if you wish to specify a deterministic seed (or if you wish to be differently nondeterministic).
our Real multi method sqrt ( Real $x: ) is export
Returns the square root of the parameter.
class Num does Real;
Num is a machine-precision numeric real value.
Complex is an immutable type. Each Complex object stores two numbers, the real and imaginary part. For all practical purposes a Complex with a NaN in real or imaginary part may be considered a NaN itself (and (NaN + 1i) ~~ NaN is True).
Coercion of a Complex to any Real returns the real part (coerced, if necessary) if the imaginary part is 0, and fails otherwise. Comparison between a Real number and a Complex must be smart enough not to coerce the Complex to a real number blindly.
our Complex multi method new(Real $re, Real $im)
Constructs a Complex number from real and imaginary part. This is the method form of $re + ($im)i.
From t/spec/S32-num/polar.t lines 5–56 (no results): (skip)
Highlighted: small|fullour Seq multi method polar (Complex $nim:) is export
Returns (magnitude, angle) corresponding to the complex number. The magnitude is non-negative, and the angle in the range -π ..^ π.
From t/spec/S32-num/complex.t lines 75–95 (no results): (skip)
Highlighted: small|fullour Real multi method re()
Returns the real part of the complex number.
From t/spec/S32-num/complex.t lines 76–95 (no results): (skip)
Highlighted: small|fullour Real multi method im()
Returns the imaginary part of a complex number.
The following are also defined in Numeric. The trig functions depend on the current (lexically scoped) trig base:
enum TrigBase is export <Radians Degrees Gradians Circles>; constant $?TRIGBASE = Radians;
Numeric multi method func ( Numeric $x: TrigBase $base = $?TRIGBASE ) is export
where func is one of: sin, cos, tan, asin, acos, atan, sec, cosec, cotan, asec, acosec, acotan, sinh, cosh, tanh, asinh, acosh, atanh, sech, cosech, cotanh, asech, acosech, acotanh.
Performs the various trigonometric functions.
Option $base is used to declare how you measure your angles. Given the value of an arc representing a single full revolution.
$base Subdivisions of circle ---- ---------------------- Radians 2*pi Degrees 360 Gradians 400 Circles 1
To change the base within your own lexical scope, it suffices to redefine the compiler constant:
constant $?TRIGBASE = Degrees;
our Numeric multi method atan2 ( Numeric $y: Numeric $x = 1 ) our Numeric multi atan2 ( Numeric $y, Numeric $x = 1 )
This second form of atan computes the arctangent of $y/$x, and takes the quadrant into account. Otherwise behaves as other trigonometric functions.
An Int is an immutable, integral number of arbitrary size.
class Rat does Real;
An immutable rational number, represented by two Ints, 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 Rat.new(2, -4).denominator return 2, because the normal form is -1/2.
multi method new(Int $num, Int $denom)
Constructs a Rat object from the numerator and denominator. Fails if $denom == 0.
our Seq[Int] multi method nude()
Returns a Seq of numerator and denominator
our Int multi method denominator()
Returns the denominator
our Int multi method numerator()
Returns the numerator
Please post errors and feedback to perl6-language. If you are making a general laundry list, please separate messages by topic.
[ Top ] [ Index of Synopses ]