lib/Math/Trig.pm

   1 #
   2 # Trigonometric functions, mostly inherited from Math::Complex.
   3 # -- Jarkko Hietaniemi, April 1997
   4 # -- Raphael Manfredi, September 1996 (indirectly: because of Math::Complex)
   5 #
   6
   7 require Exporter;
   8 package Math::Trig;
   9
  10 use strict;
  11
  12 use Math::Complex qw(:trig);
  13
  14 use vars qw($VERSION $PACKAGE
  15             @ISA
  16             @EXPORT);
  17
  18 @ISA = qw(Exporter);
  19
  20 $VERSION = 1.00;
  21
  22 my @angcnv = qw(rad_to_deg rad_to_grad
  23              deg_to_rad deg_to_grad
  24              grad_to_rad grad_to_dec);
  25
  26 @EXPORT = (@{$Math::Complex::EXPORT_TAGS{'trig'}},
  27            @angcnv);
  28
  29 use constant pi2 => 2 * pi;
  30 use constant DR  => pi2/360;
  31 use constant RD  => 360/pi2;
  32 use constant DG  => 400/360;
  33 use constant GD  => 360/400;
  34 use constant RG  => 400/pi2;
  35 use constant GR  => pi2/400;
  36
  37 #
  38 # Truncating remainder.
  39 #
  40
  41 sub remt ($$) {
  42     # Oh yes, POSIX::fmod() would be faster. Possibly. If it is available.
  43     $_[0] - $_[1] * int($_[0] / $_[1]);
  44 }
  45
  46 #
  47 # Angle conversions.
  48 #
  49
  50 sub rad_to_deg ($)  { remt(RD * $_[0], 360) }
  51
  52 sub deg_to_rad ($)  { remt(DR * $_[0], pi2) }
  53
  54 sub grad_to_deg ($) { remt(GD * $_[0], 360) }
  55
  56 sub deg_to_grad ($) { remt(DG * $_[0], 400) }
  57
  58 sub rad_to_grad ($) { remt(RG * $_[0], 400) }
  59
  60 sub grad_to_rad ($) { remt(GR * $_[0], pi2) }
  61
  62 =head1 NAME
  63
  64 Math::Trig - trigonometric functions
  65
  66 =head1 SYNOPSIS
  67
  68         use Math::Trig;
  69
  70         $x = tan(0.9);
  71         $y = acos(3.7);
  72         $z = asin(2.4);
  73
  74         $halfpi = pi/2;
  75
  76         $rad = deg_to_rad(120);
  77
  78 =head1 DESCRIPTION
  79
  80 C<Math::Trig> defines many trigonometric functions not defined by the
  81 core Perl (which defines only the C<sin()> and C<cos()>.  The constant
  82 B<pi> is also defined as are a few convenience functions for angle
  83 conversions.
  84
  85 =head1 TRIGONOMETRIC FUNCTIONS
  86
  87 The tangent
  88
  89         tan
  90
  91 The cofunctions of the sine, cosine, and tangent (cosec/csc and cotan/cot
  92 are aliases)
  93
  94         csc cosec sec cot cotan
  95
  96 The arcus (also known as the inverse) functions of the sine, cosine,
  97 and tangent
  98
  99         asin acos atan
 100
 101 The principal value of the arc tangent of y/x
 102
 103         atan2(y, x)
 104
 105 The arcus cofunctions of the sine, cosine, and tangent (acosec/acsc
 106 and acotan/acot are aliases)
 107
 108         acsc acosec asec acot acotan
 109
 110 The hyperbolic sine, cosine, and tangent
 111
 112         sinh cosh tanh
 113
 114 The cofunctions of the hyperbolic sine, cosine, and tangent (cosech/csch
 115 and cotanh/coth are aliases)
 116
 117         csch cosech sech coth cotanh
 118
 119 The arcus (also known as the inverse) functions of the hyperbolic
 120 sine, cosine, and tangent
 121
 122         asinh acosh atanh
 123
 124 The arcus cofunctions of the hyperbolic sine, cosine, and tangent
 125 (acsch/acosech and acoth/acotanh are aliases)
 126
 127         acsch acosech asech acoth acotanh
 128
 129 The trigonometric constant B<pi> is also defined.
 130
 131         $pi2 = 2 * pi;
 132
 133 =head2 ERRORS DUE TO DIVISION BY ZERO
 134
 135 The following functions
 136
 137         tan
 138         sec
 139         csc
 140         cot
 141         asec
 142         acsc
 143         tanh
 144         sech
 145         csch
 146         coth
 147         atanh
 148         asech
 149         acsch
 150         acoth
 151
 152 cannot be computed for all arguments because that would mean dividing
 153 by zero. These situations cause fatal runtime errors looking like this
 154
 155         cot(0): Division by zero.
 156         (Because in the definition of cot(0), the divisor sin(0) is 0)
 157         Died at ...
 158
 159 For the C<csc>, C<cot>, C<asec>, C<acsc>, C<csch>, C<coth>, C<asech>,
 160 C<acsch>, the argument cannot be C<0> (zero). For the C<atanh>,
 161 C<acoth>, the argument cannot be C<1> (one). For the C<tan>, C<sec>,
 162 C<tanh>, C<sech>, the argument cannot be I<pi/2 + k * pi>, where I<k> is
 163 any integer.
 164
 165 =head2 SIMPLE (REAL) ARGUMENTS, COMPLEX RESULTS
 166
 167 Please note that some of the trigonometric functions can break out
 168 from the B<real axis> into the B<complex plane>. For example
 169 C<asin(2)> has no definition for plain real numbers but it has
 170 definition for complex numbers.
 171
 172 In Perl terms this means that supplying the usual Perl numbers (also
 173 known as scalars, please see L<perldata>) as input for the
 174 trigonometric functions might produce as output results that no more
 175 are simple real numbers: instead they are complex numbers.
 176
 177 The C<Math::Trig> handles this by using the C<Math::Complex> package
 178 which knows how to handle complex numbers, please see L<Math::Complex>
 179 for more information. In practice you need not to worry about getting
 180 complex numbers as results because the C<Math::Complex> takes care of
 181 details like for example how to display complex numbers. For example:
 182
 183         print asin(2), "\n";
 184
 185 should produce something like this (take or leave few last decimals):
 186
 187         1.5707963267949-1.31695789692482i
 188
 189 That is, a complex number with the real part of approximately C<1.571>
 190 and the imaginary part of approximately C<-1.317>.
 191
 192 =head1 ANGLE CONVERSIONS
 193
 194 (Plane, 2-dimensional) angles may be converted with the following functions.
 195
 196         $radians  = deg_to_rad($degrees);
 197         $radians  = grad_to_rad($gradians);
 198
 199         $degrees  = rad_to_deg($radians);
 200         $degrees  = grad_to_deg($gradians);
 201
 202         $gradians = deg_to_grad($degrees);
 203         $gradians = rad_to_grad($radians);
 204
 205 The full circle is 2 I<pi> radians or I<360> degrees or I<400> gradians.
 206
 207 =head1 BUGS
 208
 209 Saying C<use Math::Trig;> exports many mathematical routines in the
 210 caller environment and even overrides some (C<sin>, C<cos>).  This is
 211 construed as a feature by the Authors, actually... ;-)
 212
 213 The code is not optimized for speed, especially because we use
 214 C<Math::Complex> and thus go quite near complex numbers while doing
 215 the computations even when the arguments are not. This, however,
 216 cannot be completely avoided if we want things like C<asin(2)> to give
 217 an answer instead of giving a fatal runtime error.
 218
 219 =head1 AUTHORS
 220
 221         Jarkko Hietaniemi <F<jhi@iki.fi>>
 222         Raphael Manfredi <F<Raphael_Manfredi@grenoble.hp.com>>
 223
 224 =cut
 225
 226 # eof