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