This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
[inseparable changes from match from perl-5.003_97 to perl-5.003_97a]
[perl5.git] / lib / Math / Trig.pm
CommitLineData
5aabfad6
PP
1#
2# Trigonometric functions, mostly inherited from Math::Complex.
3# -- Jarkko Hietaniemi, April 1997
4#
5
6require Exporter;
7package Math::Trig;
8
9use strict;
10
11use Math::Complex qw(:trig);
12
13use 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
22my @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
29sub pi2 () {
30 $pi2 = 2 * pi unless ($pi2);
31 $pi2;
32}
33
34sub DR () {
35 $DR = pi2/360 unless ($DR);
36 $DR;
37}
38
39sub RD () {
40 $RD = 360/pi2 unless ($RD);
41 $RD;
42}
43
44sub DG () {
45 $DG = 400/360 unless ($DG);
46 $DG;
47}
48
49sub GD () {
50 $GD = 360/400 unless ($GD);
51 $GD;
52}
53
54sub RG () {
55 $RG = 400/pi2 unless ($RG);
56 $RG;
57}
58
59sub GR () {
60 $GR = pi2/400 unless ($GR);
61 $GR;
62}
63
64#
65# Truncating remainder.
66#
67
68sub 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
77sub rad_to_deg ($) {
78 remt(RD * $_[0], 360);
79}
80
81sub deg_to_rad ($) {
82 remt(DR * $_[0], pi2);
83}
84
85sub grad_to_deg ($) {
86 remt(GD * $_[0], 360);
87}
88
89sub deg_to_grad ($) {
90 remt(DG * $_[0], 400);
91}
92
93sub rad_to_grad ($) {
94 remt(RG * $_[0], 400);
95}
96
97sub grad_to_rad ($) {
98 remt(GR * $_[0], pi2);
99}
100
101=head1 NAME
102
103Math::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
119C<Math::Trig> defines many trigonometric functions not defined by the
120core Perl (which defines only the C<sin()> and C<cos()>. The constant
121B<pi> is also defined as are a few convenience functions for angle
122conversions.
123
124=head1 TRIGONOMETRIC FUNCTIONS
125
126The tangent
127
128 tan
129
130The cofunctions of the sine, cosine, and tangent (cosec/csc and cotan/cot
131are aliases)
132
133 csc cosec sec cot cotan
134
135The arcus (also known as the inverse) functions of the sine, cosine,
136and tangent
137
138 asin acos atan
139
140The principal value of the arc tangent of y/x
141
142 atan2(y, x)
143
144The arcus cofunctions of the sine, cosine, and tangent (acosec/acsc
145and acotan/acot are aliases)
146
147 acsc acosec asec acot acotan
148
149The hyperbolic sine, cosine, and tangent
150
151 sinh cosh tanh
152
153The cofunctions of the hyperbolic sine, cosine, and tangent (cosech/csch
154and cotanh/coth are aliases)
155
156 csch cosech sech coth cotanh
157
158The arcus (also known as the inverse) functions of the hyperbolic
159sine, cosine, and tangent
160
161 asinh acosh atanh
162
163The 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
168The trigonometric constant B<pi> is also defined.
169
170 $pi2 = 2 * pi;
171
172=head2 SIMPLE ARGUMENTS, COMPLEX RESULTS
173
174Please note that some of the trigonometric functions can break out
175from the B<real axis> into the B<complex plane>. For example
176C<asin(2)> has no definition for plain real numbers but it has
177definition for complex numbers.
178
179In Perl terms this means that supplying the usual Perl numbers (also
180known as scalars, please see L<perldata>) as input for the
181trigonometric functions might produce as output results that no more
182are simple real numbers: instead they are complex numbers.
183
184The C<Math::Trig> handles this by using the C<Math::Complex> package
185which knows how to handle complex numbers, please see L<Math::Complex>
186for more information. In practice you need not to worry about getting
187complex numbers as results because the C<Math::Complex> takes care of
188details like for example how to display complex numbers. For example:
189
190 print asin(2), "\n";
191
192should produce something like this (take or leave few last decimals):
193
194 1.5707963267949-1.31695789692482i
195
196That is, a complex number with the real part of approximately E<1.571>
197and 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
212The full circle is 2 B<pi> radians or E<360> degrees or E<400> gradians.
213
214=head1
215
216The 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
233cannot be computed for all arguments because that would mean dividing
234by 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