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(rad2deg rad2grad
  23              deg2rad deg2grad
  24              grad2rad grad2deg);
  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 rad2deg ($)  { remt(RD * $_[0], 360) }
  51
  52 sub deg2rad ($)  { remt(DR * $_[0], pi2) }
  53
  54 sub grad2deg ($) { remt(GD * $_[0], 360) }
  55
  56 sub deg2grad ($) { remt(DG * $_[0], 400) }
  57
  58 sub rad2grad ($) { remt(RG * $_[0], 400) }
  59
  60 sub grad2rad ($) { 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 = deg2rad(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 or taking logarithm of zero. These situations cause fatal
 154 runtime errors looking like this
 155
 156         cot(0): Division by zero.
 157         (Because in the definition of cot(0), the divisor sin(0) is 0)
 158         Died at ...
 159
 160 or
 161
 162         atanh(-1): Logarithm of zero.
 163         Died at...
 164
 165 For the C<csc>, C<cot>, C<asec>, C<acsc>, C<acot>, C<csch>, C<coth>,
 166 C<asech>, C<acsch>, the argument cannot be C<0> (zero).  For the
 167 C<atanh>, C<acoth>, the argument cannot be C<1> (one).  For the
 168 C<atanh>, C<acoth>, the argument cannot be C<-1> (minus one).  For the
 169 C<tan>, C<sec>, C<tanh>, C<sech>, the argument cannot be I<pi/2 + k *
 170 pi>, where I<k> is any integer.
 171
 172 =head2 SIMPLE (REAL) ARGUMENTS, COMPLEX RESULTS
 173
 174 Please note that some of the trigonometric functions can break out
 175 from the B<real axis> into the B<complex plane>. For example
 176 C<asin(2)> has no definition for plain real numbers but it has
 177 definition for complex numbers.
 178
 179 In Perl terms this means that supplying the usual Perl numbers (also
 180 known as scalars, please see L<perldata>) as input for the
 181 trigonometric functions might produce as output results that no more
 182 are simple real numbers: instead they are complex numbers.
 183
 184 The C<Math::Trig> handles this by using the C<Math::Complex> package
 185 which knows how to handle complex numbers, please see L<Math::Complex>
 186 for more information. In practice you need not to worry about getting
 187 complex numbers as results because the C<Math::Complex> takes care of
 188 details like for example how to display complex numbers. For example:
 189
 190         print asin(2), "\n";
 191
 192 should produce something like this (take or leave few last decimals):
 193
 194         1.5707963267949-1.31695789692482i
 195
 196 That is, a complex number with the real part of approximately C<1.571>
 197 and the imaginary part of approximately C<-1.317>.
 198
 199 =head1 ANGLE CONVERSIONS
 200
 201 (Plane, 2-dimensional) angles may be converted with the following functions.
 202
 203         $radians  = deg2rad($degrees);
 204         $radians  = grad2rad($gradians);
 205
 206         $degrees  = rad2deg($radians);
 207         $degrees  = grad2deg($gradians);
 208
 209         $gradians = deg2grad($degrees);
 210         $gradians = rad2grad($radians);
 211
 212 The full circle is 2 I<pi> radians or I<360> degrees or I<400> gradians.
 213
 214 =head1 BUGS
 215
 216 Saying C<use Math::Trig;> exports many mathematical routines in the
 217 caller environment and even overrides some (C<sin>, C<cos>).  This is
 218 construed as a feature by the Authors, actually... ;-)
 219
 220 The code is not optimized for speed, especially because we use
 221 C<Math::Complex> and thus go quite near complex numbers while doing
 222 the computations even when the arguments are not. This, however,
 223 cannot be completely avoided if we want things like C<asin(2)> to give
 224 an answer instead of giving a fatal runtime error.
 225
 226 =head1 AUTHORS
 227
 228 Jarkko Hietaniemi <F<jhi@iki.fi>> and
 229 Raphael Manfredi <F<Raphael_Manfredi@grenoble.hp.com>>.
 230
 231 =cut
 232
 233 # eof