[inseparable changes from match from perl-5.003_97 to perl-5.003_97a]
[perl.git] / 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