lib/Math/Trig.pm

   1 #
   2 # Trigonometric functions, mostly inherited from Math::Complex.
   3 # -- Jarkko Hietaniemi, April 1997
   4 #
   5
   6 require Exporter;
   7 package Math::Trig;
   8
   9 use strict;
  10
  11 use Math::Complex qw(:trig);
  12
  13 use vars qw($VERSION $PACKAGE
  14             @ISA
  15             @EXPORT
  16             $pi2 $DR $RD $DG $GD $RG $GR);
  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 sub pi2 () {
  30     $pi2 = 2 * pi unless ($pi2);
  31     $pi2;
  32 }
  33
  34 sub DR () {
  35     $DR = pi2/360 unless ($DR);
  36     $DR;
  37 }
  38
  39 sub RD () {
  40     $RD = 360/pi2 unless ($RD);
  41     $RD;
  42 }
  43
  44 sub DG () {
  45     $DG = 400/360 unless ($DG);
  46     $DG;
  47 }
  48
  49 sub GD () {
  50     $GD = 360/400 unless ($GD);
  51     $GD;
  52 }
  53
  54 sub RG () {
  55     $RG = 400/pi2 unless ($RG);
  56     $RG;
  57 }
  58
  59 sub GR () {
  60     $GR = pi2/400 unless ($GR);
  61     $GR;
  62 }
  63
  64 #
  65 # Truncating remainder.
  66 #
  67
  68 sub remt ($$) {
  69     # Oh yes, POSIX::fmod() would be faster. Possibly. If it is available.
  70     $_[0] - $_[1] * int($_[0] / $_[1]);
  71 }
  72
  73 #
  74 # Angle conversions.
  75 #
  76
  77 sub rad_to_deg ($) {
  78     remt(RD * $_[0], 360);
  79 }
  80
  81 sub deg_to_rad ($) {
  82     remt(DR * $_[0], pi2);
  83 }
  84
  85 sub grad_to_deg ($) {
  86     remt(GD * $_[0], 360);
  87 }
  88
  89 sub deg_to_grad ($) {
  90     remt(DG * $_[0], 400);
  91 }
  92
  93 sub rad_to_grad ($) {
  94     remt(RG * $_[0], 400);
  95 }
  96
  97 sub grad_to_rad ($) {
  98     remt(GR * $_[0], pi2);
  99 }
 100
 101 =head1 NAME
 102
 103 Math::Trig - trigonometric functions
 104
 105 =head1 SYNOPSIS
 106
 107         use Math::Trig;
 108
 109         $x = tan(0.9);
 110         $y = acos(3.7);
 111         $z = asin(2.4);
 112
 113         $halfpi = pi/2;
 114
 115         $rad = deg_to_rad(120);
 116
 117 =head1 DESCRIPTION
 118
 119 C<Math::Trig> defines many trigonometric functions not defined by the
 120 core Perl (which defines only the C<sin()> and C<cos()>.  The constant
 121 B<pi> is also defined as are a few convenience functions for angle
 122 conversions.
 123
 124 =head1 TRIGONOMETRIC FUNCTIONS
 125
 126 The tangent
 127
 128         tan
 129
 130 The cofunctions of the sine, cosine, and tangent (cosec/csc and cotan/cot
 131 are aliases)
 132
 133         csc cosec sec cot cotan
 134
 135 The arcus (also known as the inverse) functions of the sine, cosine,
 136 and tangent
 137
 138         asin acos atan
 139
 140 The principal value of the arc tangent of y/x
 141
 142         atan2(y, x)
 143
 144 The arcus cofunctions of the sine, cosine, and tangent (acosec/acsc
 145 and acotan/acot are aliases)
 146
 147         acsc acosec asec acot acotan
 148
 149 The hyperbolic sine, cosine, and tangent
 150
 151         sinh cosh tanh
 152
 153 The cofunctions of the hyperbolic sine, cosine, and tangent (cosech/csch
 154 and cotanh/coth are aliases)
 155
 156         csch cosech sech coth cotanh
 157
 158 The arcus (also known as the inverse) functions of the hyperbolic
 159 sine, cosine, and tangent
 160
 161         asinh acosh atanh
 162
 163 The arcus cofunctions of the hyperbolic sine, cosine, and tangent
 164 (acsch/acosech and acoth/acotanh are aliases)
 165
 166         acsch acosech asech acoth acotanh
 167
 168 The trigonometric constant B<pi> is also defined.
 169
 170         $pi2 = 2 * pi;
 171
 172 =head2 SIMPLE 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 E<1.571>
 197 and the imaginary part of approximately E<-1.317>.
 198
 199 =head1 ANGLE CONVERSIONS
 200
 201 (Plane, 2-dimensional) angles may be converted with the following functions.
 202
 203         $radians  = deg_to_rad($degrees);
 204         $radians  = grad_to_rad($gradians);
 205
 206         $degrees  = rad_to_deg($radians);
 207         $degrees  = grad_to_deg($gradians);
 208
 209         $gradians = deg_to_grad($degrees);
 210         $gradians = rad_to_grad($radians);
 211
 212 The full circle is 2 B<pi> radians or E<360> degrees or E<400> gradians.
 213
 214 =head1
 215
 216 The following functions
 217
 218         tan
 219         sec
 220         csc
 221         cot
 222         atan
 223         acot
 224         tanh
 225         sech
 226         csch
 227         coth
 228         atanh
 229         asech
 230         acsch
 231         acoth
 232
 233 cannot be computed for all arguments because that would mean dividing
 234 by zero. These situations cause fatal runtime errors looking like this
 235
 236         cot(0): Division by zero.
 237         (Because in the definition of cot(0), sin(0) is 0)
 238         Died at ...
 239
 240 =cut
 241
 242 # eof